feature/recipe_implementation #5
613
README.md
613
README.md
@ -7,8 +7,21 @@ Grokkit is a fast Go CLI integrating Grok AI with git workflows and general chat
|
|||||||
[]()
|
[]()
|
||||||
[]()
|
[]()
|
||||||
|
|
||||||
## 🚀 Quick Start
|
## Requirements
|
||||||
|
|
||||||
|
- Go 1.24.2 (for building)
|
||||||
|
- Git (for git-related commands)
|
||||||
|
- XAI API key
|
||||||
|
|
||||||
|
## 🚀 Quick Start Installation
|
||||||
|
|
||||||
|
### From pre-built release (recommended)
|
||||||
|
```bash
|
||||||
|
VERSION=0.1.3 # Replace with latest version tag (omit 'v')
|
||||||
|
curl -L https://repos.gmgauthier.com/gmgauthier/grokkit/releases/download/v${VERSION}/grokkit-install.sh | VERSION=${VERSION} bash -
|
||||||
|
```
|
||||||
|
|
||||||
|
### From Source (for development)
|
||||||
```bash
|
```bash
|
||||||
# Set your API key
|
# Set your API key
|
||||||
export XAI_API_KEY=sk-...
|
export XAI_API_KEY=sk-...
|
||||||
@ -16,370 +29,23 @@ export XAI_API_KEY=sk-...
|
|||||||
# Install from source
|
# Install from source
|
||||||
git clone https://repos.gmgauthier.com/gmgauthier/grokkit.git
|
git clone https://repos.gmgauthier.com/gmgauthier/grokkit.git
|
||||||
cd grokkit
|
cd grokkit
|
||||||
make install
|
make test
|
||||||
|
|
||||||
# Or build locally
|
|
||||||
make build
|
make build
|
||||||
|
make install
|
||||||
|
````
|
||||||
|
|
||||||
# Verify installation
|
### Verify:
|
||||||
grokkit --help
|
|
||||||
|
|
||||||
### From pre-built release (recommended)
|
|
||||||
```bash
|
|
||||||
VERSION=0.1.3 # Replace with latest version tag (omit 'v')
|
|
||||||
curl -L https://repos.gmgauthier.com/gmgauthier/grokkit/releases/download/v${VERSION}/grokkit-install.sh | VERSION=${VERSION} bash -
|
|
||||||
```
|
|
||||||
Verify:
|
|
||||||
```bash
|
```bash
|
||||||
grokkit version
|
grokkit version
|
||||||
```
|
```
|
||||||
|
|
||||||
## 📋 Table of Contents
|
|
||||||
|
|
||||||
- [Commands](#commands)
|
|
||||||
- [chat](#-grokkit-chat)
|
|
||||||
- [query](#-grokkit-query)
|
|
||||||
- [edit](#-grokkit-edit-file-instruction)
|
|
||||||
- [commit-msg](#-grokkit-commit-msg)
|
|
||||||
- [commit](#-grokkit-commit)
|
|
||||||
- [review](#-grokkit-review)
|
|
||||||
- [pr-describe](#-grokkit-pr-describe)
|
|
||||||
- [history](#-grokkit-history)
|
|
||||||
- [changelog](#-grokkit-changelog)
|
|
||||||
- [lint](#-grokkit-lint-file)
|
|
||||||
- [docs](#-grokkit-docs-file)
|
|
||||||
- [testgen](#-grokkit-testgen)
|
|
||||||
- [scaffold](#-grokkit-scaffold-file-description)
|
|
||||||
- [recipe](#-grokkit-recipe-run-recipe)
|
|
||||||
- [agent](#-grokkit-agent)
|
|
||||||
- [Configuration](#configuration)
|
|
||||||
- [Workflows](#workflows)
|
|
||||||
- [Shell Completions](#shell-completions)
|
|
||||||
- [Features](#features)
|
|
||||||
- [Development](#development)
|
|
||||||
- [Documentation](#documentation)
|
|
||||||
- [License](#license)
|
|
||||||
|
|
||||||
## Commands
|
|
||||||
|
|
||||||
### 💬 `grokkit chat`
|
|
||||||
Interactive CLI chat with Grok. Features persistent history across sessions.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
grokkit chat # Start chat session
|
|
||||||
grokkit chat -m grok-beta # Use specific model
|
|
||||||
grokkit chat --debug # Enable debug logging
|
|
||||||
```
|
|
||||||
|
|
||||||
**Tips:**
|
|
||||||
- Type `/quit`, `/q`, or `exit` to exit
|
|
||||||
- History is saved automatically between sessions
|
|
||||||
- Use `--debug` to see API request timing
|
|
||||||
|
|
||||||
### 🤖 `grokkit query`
|
|
||||||
|
|
||||||
One-shot technical question answering. Perfect for quick programming or engineering questions.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Basic usage
|
|
||||||
grokkit query "How do I sort a slice of structs by a field in Go?"
|
|
||||||
|
|
||||||
# Longer, more detailed answer
|
|
||||||
grokkit query --wordy "Explain how Go's context package works with cancellation"
|
|
||||||
```
|
|
||||||
Features:
|
|
||||||
|
|
||||||
Default mode is concise, factual, and actionable
|
|
||||||
--wordy flag gives longer, more explanatory answers
|
|
||||||
Uses the fast non-reasoning model by default for speed
|
|
||||||
No persistent history or interactive chat UI
|
|
||||||
|
|
||||||
|
|
||||||
### ✏️ `grokkit edit FILE "instruction"`
|
|
||||||
AI-powered file editing with preview.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Basic usage
|
|
||||||
grokkit edit main.go "add error handling to all functions"
|
|
||||||
|
|
||||||
# Complex refactoring
|
|
||||||
grokkit edit server.go "convert this to use context for cancellation"
|
|
||||||
|
|
||||||
# Add features
|
|
||||||
grokkit edit api.go "add rate limiting middleware"
|
|
||||||
|
|
||||||
# Documentation
|
|
||||||
grokkit edit utils.go "add detailed docstrings to all exported functions"
|
|
||||||
```
|
|
||||||
|
|
||||||
**Safety features:**
|
|
||||||
- Shows preview with diff-style output
|
|
||||||
- Requires confirmation before applying
|
|
||||||
- Uses silent streaming (no console spam)
|
|
||||||
|
|
||||||
### 📝 `grokkit commit-msg`
|
|
||||||
Generate conventional commit messages from staged changes.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git add .
|
|
||||||
grokkit commit-msg # Generate message only
|
|
||||||
grokkit commit-msg -m grok-4 # Use specific model
|
|
||||||
```
|
|
||||||
|
|
||||||
Output format: `type(scope): subject\n\nbody`
|
|
||||||
|
|
||||||
### ✅ `grokkit commit`
|
|
||||||
Generate commit message and commit in one step.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git add .
|
|
||||||
grokkit commit # Generate + confirm + commit
|
|
||||||
```
|
|
||||||
|
|
||||||
### 🔍 `grokkit review`
|
|
||||||
AI code review of staged or unstaged changes.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Review staged changes
|
|
||||||
git add feature.go
|
|
||||||
grokkit review
|
|
||||||
|
|
||||||
# Review all changes
|
|
||||||
grokkit review
|
|
||||||
|
|
||||||
# Get detailed review
|
|
||||||
grokkit review --debug # See API timing info
|
|
||||||
```
|
|
||||||
|
|
||||||
Output includes:
|
|
||||||
- Summary of changes
|
|
||||||
- 3-5 actionable improvements
|
|
||||||
- Potential bugs or issues
|
|
||||||
- Best practice suggestions
|
|
||||||
|
|
||||||
### 📋 `grokkit pr-describe`
|
|
||||||
Generate comprehensive PR descriptions.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# From current branch vs master
|
|
||||||
grokkit pr-describe
|
|
||||||
|
|
||||||
# Compare against a specific base branch
|
|
||||||
grokkit pr-describe --base main
|
|
||||||
|
|
||||||
# With specific model
|
|
||||||
grokkit pr-describe -m grok-4
|
|
||||||
```
|
|
||||||
|
|
||||||
Output includes:
|
|
||||||
- Title suggestion
|
|
||||||
- Summary of changes
|
|
||||||
- Motivation/context
|
|
||||||
- Testing notes
|
|
||||||
|
|
||||||
### 📜 `grokkit history`
|
|
||||||
Summarize recent git commits.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
grokkit history # Last 10 commits
|
|
||||||
```
|
|
||||||
|
|
||||||
### 🗒️ `grokkit changelog`
|
|
||||||
|
|
||||||
Generate a clean `CHANGELOG.md` section from git history, designed specifically so the output can be pasted directly into Gitea release notes.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 1. Create your version tag first
|
|
||||||
git tag v0.2.0
|
|
||||||
|
|
||||||
# 2. Generate preview + write (with safety confirmation)
|
|
||||||
grokkit changelog
|
|
||||||
|
|
||||||
# 3. Output ONLY the new section (perfect for Gitea "Release notes")
|
|
||||||
grokkit changelog --stdout
|
|
||||||
|
|
||||||
# 4. Write file + get commit reminder
|
|
||||||
grokkit changelog --commit
|
|
||||||
```
|
|
||||||
|
|
||||||
### 📖 `grokkit docs <file> [file...]`
|
|
||||||
Generate language-appropriate documentation comments using Grok AI.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Preview and confirm
|
|
||||||
grokkit docs main.go
|
|
||||||
|
|
||||||
# Auto-apply without confirmation
|
|
||||||
grokkit docs handlers.go models.go --auto-apply
|
|
||||||
|
|
||||||
# Document multiple files at once
|
|
||||||
grokkit docs cmd/*.go --auto-apply
|
|
||||||
|
|
||||||
# Use specific model
|
|
||||||
grokkit docs app.py -m grok-4
|
|
||||||
```
|
|
||||||
|
|
||||||
**Supported doc styles by language:**
|
|
||||||
|
|
||||||
| Language | Style |
|
|
||||||
|----------|-------|
|
|
||||||
| Go | godoc (`// FuncName does...`) |
|
|
||||||
| Python | PEP 257 docstrings (`"""Summary\n\nArgs:..."""`) |
|
|
||||||
| C / C++ | Doxygen (`/** @brief ... @param ... @return ... */`) |
|
|
||||||
| JavaScript / TypeScript | JSDoc (`/** @param {type} name ... */`) |
|
|
||||||
| Rust | rustdoc (`/// Summary\n/// # Arguments`) |
|
|
||||||
| Ruby | YARD (`# @param [Type] name`) |
|
|
||||||
| Java | Javadoc (`/** @param ... @return ... */`) |
|
|
||||||
| Shell | Shell comments (`# function: desc, # Args: ...`) |
|
|
||||||
|
|
||||||
**Safety features:**
|
|
||||||
- Shows first 50 lines of documented code as preview
|
|
||||||
- Requires confirmation (unless `--auto-apply`)
|
|
||||||
|
|
||||||
### 🧪 `grokkit testgen PATHS...`
|
|
||||||
|
|
||||||
**Description**: Generate comprehensive unit tests for Go/Python/C/C++ files using AI.
|
|
||||||
|
|
||||||
**Benefits**:
|
|
||||||
- Go: Table-driven `t.Parallel()` matching codebase.
|
|
||||||
- Python: Pytest with `@parametrize`.
|
|
||||||
- C: Check framework suites.
|
|
||||||
- C++: Google Test `EXPECT_*`.
|
|
||||||
- Boosts coverage; safe preview.
|
|
||||||
|
|
||||||
**CLI examples**:
|
|
||||||
```bash
|
|
||||||
grokkit testgen internal/grok/client.go
|
|
||||||
grokkit testgen app.py --yes
|
|
||||||
grokkit testgen foo.c bar.cpp
|
|
||||||
```
|
|
||||||
|
|
||||||
**Safety features**:
|
|
||||||
- Lang detection via `internal/linter`.
|
|
||||||
- Unified diff preview.
|
|
||||||
- Y/N (--yes auto).
|
|
||||||
|
|
||||||
### 🏗️ `grokkit scaffold FILE "DESCRIPTION"`
|
|
||||||
|
|
||||||
**Description**: Scaffold a new file with Grok using project context for style matching.
|
|
||||||
|
|
||||||
**CLI examples**:
|
|
||||||
```bash
|
|
||||||
# Basic usage
|
|
||||||
grokkit scaffold internal/git/utils.go "git wrapper for listing tags"
|
|
||||||
|
|
||||||
# Scaffold with a basic test file
|
|
||||||
grokkit scaffold app.py "Flask route for health checks" --with-tests
|
|
||||||
|
|
||||||
# Preview without writing
|
|
||||||
grokkit scaffold main.go "simple CLI entrypoint" --dry-run
|
|
||||||
```
|
|
||||||
|
|
||||||
**Features**:
|
|
||||||
- Project context harvesting (siblings/style matching).
|
|
||||||
- Optional test generation (`--with-tests`).
|
|
||||||
- Safety checks (won't overwrite without `--force`).
|
|
||||||
- Language detection and overrides (`--lang`).
|
|
||||||
|
|
||||||
### 👨🍳 `grokkit recipe run [name|path]`
|
|
||||||
|
|
||||||
**Description**: Execute transactional "recipes" for complex, multi-step AI workflows.
|
|
||||||
|
|
||||||
**CLI examples**:
|
|
||||||
```bash
|
|
||||||
# Run a project-local recipe
|
|
||||||
grokkit recipe run result-refactor
|
|
||||||
|
|
||||||
# Pass parameters to the recipe
|
|
||||||
grokkit recipe run result-refactor -p package_path=internal/git -p dry_run=false
|
|
||||||
|
|
||||||
# Run a specific recipe file
|
|
||||||
grokkit recipe run ./my-custom-recipe.md
|
|
||||||
```
|
|
||||||
|
|
||||||
**Recipe System**:
|
|
||||||
- **Local Recipes**: Stored in `.grokkit/recipes/*.md`.
|
|
||||||
- **Global Recipes**: Stored in `~/.local/share/grokkit/recipes/*.md`.
|
|
||||||
- Recipes are markdown-based with YAML frontmatter for parameters and configuration.
|
|
||||||
|
|
||||||
### 🤖 `grokkit agent`
|
|
||||||
Multi-file agent for complex refactoring (experimental).
|
|
||||||
|
|
||||||
```bash
|
|
||||||
grokkit agent "refactor authentication to use JWT"
|
|
||||||
```
|
|
||||||
|
|
||||||
### 🔧 `grokkit lint FILE`
|
|
||||||
Automatically detect language, run linter, and apply AI-suggested fixes.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Just check for issues (no fixes)
|
|
||||||
grokkit lint main.go --dry-run
|
|
||||||
|
|
||||||
# Interactive fix (preview + confirmation)
|
|
||||||
grokkit lint app.py
|
|
||||||
|
|
||||||
# Auto-fix without confirmation
|
|
||||||
grokkit lint server.js --auto-fix
|
|
||||||
|
|
||||||
# Use specific model
|
|
||||||
grokkit lint script.rb -m grok-4
|
|
||||||
```
|
|
||||||
|
|
||||||
**Supported languages:**
|
|
||||||
- **Go** (golangci-lint, go vet)
|
|
||||||
- **Python** (pylint, flake8, ruff)
|
|
||||||
- **JavaScript/JSX** (eslint)
|
|
||||||
- **TypeScript/TSX** (eslint, tsc)
|
|
||||||
- **Rust** (clippy)
|
|
||||||
- **Ruby** (rubocop)
|
|
||||||
- **Java** (checkstyle)
|
|
||||||
- **C/C++** (clang-tidy)
|
|
||||||
- **Shell** (shellcheck)
|
|
||||||
|
|
||||||
**Safety features:**
|
|
||||||
- Shows preview of fixes
|
|
||||||
- Verifies fixes by re-running linter
|
|
||||||
- Requires confirmation (unless `--auto-fix`)
|
|
||||||
|
|
||||||
## Safety & Change Management
|
|
||||||
|
|
||||||
Grokkit is designed to work seamlessly with Git. Rather than creating redundant `.bak` files, we lean on Git's powerful version control to manage changes and rollbacks.
|
|
||||||
|
|
||||||
### The Safety Workflow
|
|
||||||
|
|
||||||
1. **Preview**: Every command that modifies files (like `edit`, `lint`, `docs`) shows a diff-style preview first.
|
|
||||||
2. **Confirm**: You must explicitly confirm (`y/N`) before any changes are written to disk.
|
|
||||||
3. **Git Integration**: Use Git to manage the "pre-staged," "staged," and "committed" degrees of change.
|
|
||||||
|
|
||||||
### Managing Undesired Changes
|
|
||||||
|
|
||||||
If you've applied a change that you don't like, Git makes it easy to roll back:
|
|
||||||
|
|
||||||
- **Unstaged changes**: If you haven't `git add`-ed the changes yet:
|
|
||||||
```bash
|
|
||||||
git restore <file>
|
|
||||||
```
|
|
||||||
- **Staged changes**: If you've already staged the changes:
|
|
||||||
```bash
|
|
||||||
git restore --staged <file>
|
|
||||||
git restore <file>
|
|
||||||
```
|
|
||||||
- **Committed changes**: If you've already committed the changes:
|
|
||||||
```bash
|
|
||||||
git revert HEAD
|
|
||||||
# or to reset to a previous state:
|
|
||||||
git reset --hard HEAD~1
|
|
||||||
```
|
|
||||||
|
|
||||||
By using Git, you have a complete audit trail and multiple levels of undo, ensuring your codebase remains stable even when experimenting with AI-driven refactors.
|
|
||||||
|
|
||||||
## Configuration
|
## Configuration
|
||||||
|
|
||||||
### Environment Variables
|
### Environment Variables
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
export XAI_API_KEY=sk-... # Required: Your xAI API key
|
export XAI_API_KEY=sk-... # Required: Your xAI API key
|
||||||
|
export XAI_API_KEY=$(vault read -field=key secret/grokkit) # Recommended for secure storage
|
||||||
```
|
```
|
||||||
|
|
||||||
### Config File (Optional)
|
### Config File (Optional)
|
||||||
@ -400,7 +66,19 @@ fast = "grok-4-1-fast-non-reasoning"
|
|||||||
history_file = "~/.config/grokkit/chat_history.json"
|
history_file = "~/.config/grokkit/chat_history.json"
|
||||||
```
|
```
|
||||||
|
|
||||||
**See also:** [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for advanced configuration options.
|
**See also:** [docs/developer-guide/CONFIGURATION.md](docs/developer-guide/CONFIGURATION.md) for advanced configuration options.
|
||||||
|
|
||||||
|
|
||||||
|
## 📖 Commands
|
||||||
|
|
||||||
|
See [The User Guide](docs/user-guide/index.md) for complete details on command usage.
|
||||||
|
|
||||||
|
## 🛡️ Safety & Change Management
|
||||||
|
|
||||||
|
Grokkit is designed to work seamlessly with Git, using version control instead of redundant backup files to manage changes and rollbacks.
|
||||||
|
|
||||||
|
[Read the Safety & Change Management Guide](docs/user-guide/safety.md)
|
||||||
|
|
||||||
|
|
||||||
### Logging
|
### Logging
|
||||||
|
|
||||||
@ -419,121 +97,15 @@ cat ~/.config/grokkit/grokkit.log | jq 'select(.msg=="API request completed") |
|
|||||||
|
|
||||||
## Workflows
|
## Workflows
|
||||||
|
|
||||||
### Git Workflow Integration
|
Common usage patterns to integrate Grokkit into your development cycle.
|
||||||
|
|
||||||
```bash
|
[Read the Workflows Guide](docs/user-guide/workflows.md)
|
||||||
# 1. Make changes
|
|
||||||
vim src/api.go
|
|
||||||
|
|
||||||
# 2. Review with AI
|
|
||||||
git add src/api.go
|
|
||||||
grokkit review
|
|
||||||
|
|
||||||
# 3. Fix issues, then commit
|
|
||||||
git add src/api.go
|
|
||||||
grokkit commit
|
|
||||||
|
|
||||||
# 4. Generate PR description
|
|
||||||
grokkit pr-describe
|
|
||||||
```
|
|
||||||
|
|
||||||
### Code Refactoring Workflow
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 1. Chat to plan approach
|
|
||||||
grokkit chat
|
|
||||||
> "How should I refactor this authentication code to use middleware?"
|
|
||||||
|
|
||||||
# 2. Apply changes with edit
|
|
||||||
grokkit edit auth.go "implement middleware pattern as discussed"
|
|
||||||
|
|
||||||
# 3. Review changes
|
|
||||||
grokkit review
|
|
||||||
|
|
||||||
# 4. Commit
|
|
||||||
grokkit commit
|
|
||||||
```
|
|
||||||
|
|
||||||
### Debugging Workflow
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 1. Describe issue in chat
|
|
||||||
grokkit chat --debug
|
|
||||||
> "I'm getting a nil pointer error in handler.go:42"
|
|
||||||
|
|
||||||
# 2. Apply suggested fixes
|
|
||||||
grokkit edit handler.go "add nil checks before dereferencing user object"
|
|
||||||
|
|
||||||
# 3. Verify and commit
|
|
||||||
grokkit review
|
|
||||||
grokkit commit
|
|
||||||
```
|
|
||||||
|
|
||||||
### Batch File Editing
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Edit multiple files with consistent changes
|
|
||||||
for file in src/*.go; do
|
|
||||||
grokkit edit "$file" "add context parameter to all exported functions"
|
|
||||||
done
|
|
||||||
|
|
||||||
# Review all changes together
|
|
||||||
grokkit review
|
|
||||||
```
|
|
||||||
|
|
||||||
### Code Quality Workflow
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 1. Check a file for linting issues
|
|
||||||
grokkit lint app.py --dry-run
|
|
||||||
|
|
||||||
# 2. Apply AI-suggested fixes with preview
|
|
||||||
grokkit lint app.py
|
|
||||||
|
|
||||||
# 3. Auto-fix multiple files
|
|
||||||
for file in src/*.js; do
|
|
||||||
grokkit lint "$file" --auto-fix
|
|
||||||
done
|
|
||||||
|
|
||||||
# 4. Review and commit
|
|
||||||
grokkit review
|
|
||||||
grokkit commit
|
|
||||||
```
|
|
||||||
|
|
||||||
### Documentation Generation Workflow
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 1. Preview docs for a single file
|
|
||||||
grokkit docs internal/api/handler.go
|
|
||||||
|
|
||||||
# 2. Batch-document a package
|
|
||||||
grokkit docs cmd/*.go --auto-apply
|
|
||||||
|
|
||||||
# 3. Document across languages in one pass
|
|
||||||
grokkit docs lib/utils.py src/helpers.ts --auto-apply
|
|
||||||
|
|
||||||
# 4. Review and commit
|
|
||||||
grokkit review
|
|
||||||
grokkit commit
|
|
||||||
```
|
|
||||||
|
|
||||||
## Shell Completions
|
## Shell Completions
|
||||||
|
|
||||||
Generate shell completions for faster command entry:
|
Generate shell completions for faster command entry:
|
||||||
|
|
||||||
```bash
|
[Read the full Completion Guide](docs/user-guide/completion.md)
|
||||||
# Bash
|
|
||||||
grokkit completion bash | sudo tee /etc/bash_completion.d/grokkit
|
|
||||||
|
|
||||||
# Zsh (oh-my-zsh)
|
|
||||||
grokkit completion zsh > ~/.oh-my-zsh/completions/_grokkit
|
|
||||||
|
|
||||||
# Fish
|
|
||||||
grokkit completion fish > ~/.config/fish/completions/grokkit.fish
|
|
||||||
|
|
||||||
# PowerShell
|
|
||||||
grokkit completion powershell | Out-String | Invoke-Expression
|
|
||||||
```
|
|
||||||
|
|
||||||
## Flags
|
## Flags
|
||||||
|
|
||||||
@ -608,113 +180,9 @@ grokkit review -v
|
|||||||
|
|
||||||
## Development
|
## Development
|
||||||
|
|
||||||
```bash
|
Comprehensive build instructions, project structure details, and the Grokkit development workflow.
|
||||||
# All tests pass without XAI_API_KEY (unit tests only)
|
|
||||||
|
|
||||||
# Run tests
|
[Read the Development Overview Guide](docs/developer-guide/overview.md)
|
||||||
make test
|
|
||||||
|
|
||||||
# Agent-specific tests
|
|
||||||
make test-agent
|
|
||||||
|
|
||||||
# Run tests with coverage report
|
|
||||||
make test-cover
|
|
||||||
open build/coverage.html
|
|
||||||
|
|
||||||
# Linting (matches CI, uses .golangci.yml config)
|
|
||||||
make lint
|
|
||||||
# Install golangci-lint if needed:
|
|
||||||
# go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
|
|
||||||
|
|
||||||
# Run specific tests
|
|
||||||
go test -run TestEditCommand ./cmd -v
|
|
||||||
|
|
||||||
# Build binary
|
|
||||||
make build
|
|
||||||
|
|
||||||
# Install locally
|
|
||||||
make install
|
|
||||||
|
|
||||||
# Clean build artifacts
|
|
||||||
make clean
|
|
||||||
```
|
|
||||||
|
|
||||||
### Project Structure
|
|
||||||
|
|
||||||
```
|
|
||||||
grokkit/
|
|
||||||
├── cmd/ # CLI commands (Cobra)
|
|
||||||
│ ├── docs.go # grokkit docs — AI documentation generation
|
|
||||||
│ ├── lint.go # grokkit lint — AI-powered linting
|
|
||||||
│ ├── recipe.go # grokkit recipe — transactional recipe runner
|
|
||||||
│ ├── scaffold.go # grokkit scaffold — project-aware file generation
|
|
||||||
│ └── ... # chat, edit, commit, review, history, pr-describe, agent
|
|
||||||
├── config/ # Viper configuration
|
|
||||||
├── docs/ # Documentation
|
|
||||||
├── .grokkit/ # Project-local Grokkit data
|
|
||||||
│ └── recipes/ # Custom AI workflows (recipes)
|
|
||||||
├── todo/ # TODO tracking: queued/ (pending) and completed/ (historical record)
|
|
||||||
│ ├── queued/ # Pending TODO items
|
|
||||||
│ └── completed/ # Completed TODO items with history
|
|
||||||
├── internal/
|
|
||||||
│ ├── errors/ # Custom error types
|
|
||||||
│ ├── git/ # Git operations
|
|
||||||
│ ├── grok/ # xAI Grok API client
|
|
||||||
│ ├── linter/ # Multi-language linting
|
|
||||||
│ ├── logger/ # Structured slog logging
|
|
||||||
│ ├── recipe/ # Recipe loading and execution engine
|
|
||||||
│ └── version/ # Build/version info
|
|
||||||
├── main.go # Application entrypoint
|
|
||||||
├── go.mod # Dependencies
|
|
||||||
├── Makefile # Build automation
|
|
||||||
├── .golangci.yml # Golangci-lint configuration
|
|
||||||
└── scripts/ # Install scripts
|
|
||||||
```
|
|
||||||
|
|
||||||
### TODO Workflow
|
|
||||||
|
|
||||||
**Policy:**
|
|
||||||
From now on, the only thing to be committed directly to the `master` branch will be to-do items (.md files in `todo/queued/`).
|
|
||||||
|
|
||||||
**Process:**
|
|
||||||
1. When deciding to work on a to-do item: create a branch, implement on the branch, submit PR to `master`.
|
|
||||||
2. After PR merge: move the item to `todo/completed/`.
|
|
||||||
|
|
||||||
**Example workflow:**
|
|
||||||
```bash
|
|
||||||
git checkout -b feature/some-todo
|
|
||||||
# Implement changes, test with make test lint
|
|
||||||
git add .
|
|
||||||
git commit -m "feat: implement some-todo"
|
|
||||||
git push -u origin feature/some-todo
|
|
||||||
# Create and merge PR to master
|
|
||||||
|
|
||||||
# Post-merge:
|
|
||||||
git checkout master
|
|
||||||
git pull
|
|
||||||
mv "todo/queued/SOME_TODO.md" "todo/completed/SOME_TODO.md"
|
|
||||||
git add todo/
|
|
||||||
git commit -m "chore: complete some-todo"
|
|
||||||
git push origin master
|
|
||||||
```
|
|
||||||
|
|
||||||
### Gitea Actions Automation *(automates post-merge above)*
|
|
||||||
|
|
||||||
[`.gitea/workflows/auto-complete-todo.yml`](.gitea/workflows/auto-complete-todo.yml) triggers on PR `opened`/`synchronize`:
|
|
||||||
|
|
||||||
- Branches `feature/some-todo`: moves `todo/queued/some-todo.md` → `completed/`.
|
|
||||||
|
|
||||||
**One-time setup** (Gitea → Repo → Settings → Secrets & Variables → Actions):
|
|
||||||
- New Secret: `PAT_TOKEN` = [Personal Access Token](https://gitea.example.com/user/settings/tokens) (scope: `repo`).
|
|
||||||
- Optional: Branch protection → Require "Auto-complete TODO" status check.
|
|
||||||
|
|
||||||
**Result**: No manual post-merge steps needed!
|
|
||||||
|
|
||||||
## Documentation
|
|
||||||
|
|
||||||
- 📖 [Troubleshooting Guide](docs/TROUBLESHOOTING.md) - Common issues and solutions
|
|
||||||
- 🏗️ [Architecture Overview](docs/ARCHITECTURE.md) - System design and patterns
|
|
||||||
- ⚙️ [Configuration Guide](docs/CONFIGURATION.md) - Advanced configuration options
|
|
||||||
|
|
||||||
## API Usage & Costs
|
## API Usage & Costs
|
||||||
|
|
||||||
@ -724,11 +192,6 @@ Grokkit uses the xAI Grok API. Be aware:
|
|||||||
- Streaming reduces perceived latency
|
- Streaming reduces perceived latency
|
||||||
- Consider using model aliases for different use cases (fast/expensive)
|
- Consider using model aliases for different use cases (fast/expensive)
|
||||||
|
|
||||||
## Requirements
|
|
||||||
|
|
||||||
- Go 1.24.2 (for building)
|
|
||||||
- Git (for git-related commands)
|
|
||||||
- XAI API key
|
|
||||||
|
|
||||||
## Troubleshooting
|
## Troubleshooting
|
||||||
|
|
||||||
@ -747,7 +210,7 @@ Error: Request failed: context deadline exceeded
|
|||||||
→ Solution: chmod 644 ~/.config/grokkit/grokkit.log
|
→ Solution: chmod 644 ~/.config/grokkit/grokkit.log
|
||||||
```
|
```
|
||||||
|
|
||||||
**See [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) for more details.**
|
**See [docs/developer-guide/TROUBLESHOOTING.md](docs/developer-guide/TROUBLESHOOTING.md) for more details.**
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
|
|||||||
@ -16,28 +16,33 @@ This document describes the design principles, architecture patterns, and implem
|
|||||||
|
|
||||||
Grokkit follows these core principles:
|
Grokkit follows these core principles:
|
||||||
|
|
||||||
### 1. **Simplicity First**
|
### 1. **The Developer Is The Agent**
|
||||||
|
- The developer is in control of the code, not the LLM.
|
||||||
|
- The LLM should *enhance the developer experience*, not *replace* it.
|
||||||
|
- The developer is the one who makes **informed judgments** about the code, not the LLM.
|
||||||
|
|
||||||
|
### 2. **Simplicity First**
|
||||||
- Minimal dependencies (stdlib + well-known libs)
|
- Minimal dependencies (stdlib + well-known libs)
|
||||||
- Minimal interface surface (CLI commands over TUI interactions)
|
- Minimal interface surface (CLI commands over TUI interactions)
|
||||||
- Clear, readable code over clever solutions
|
- Clear, readable code over clever solutions
|
||||||
- Single responsibility per package
|
- Single responsibility per package
|
||||||
|
|
||||||
### 2. **Safety by Default**
|
### 3. **Safety by Default**
|
||||||
- Git-based version control for change management
|
- Git-based version control for change management
|
||||||
- Confirmation prompts for destructive actions
|
- Confirmation prompts for destructive actions
|
||||||
- Comprehensive error handling
|
- Comprehensive error handling
|
||||||
|
|
||||||
### 3. **Observability**
|
### 4. **Observability**
|
||||||
- Structured logging for all operations
|
- Structured logging for all operations
|
||||||
- Request/response timing
|
- Request/response timing
|
||||||
- Contextual error messages
|
- Contextual error messages
|
||||||
|
|
||||||
### 4. **Testability**
|
### 5. **Testability**
|
||||||
- Interface-based design
|
- Interface-based design
|
||||||
- Dependency injection where needed
|
- Dependency injection where needed
|
||||||
- Unit tests for pure functions
|
- Unit tests for pure functions
|
||||||
|
|
||||||
### 5. **User Experience**
|
### 6. **User Experience**
|
||||||
- Streaming responses for immediate feedback
|
- Streaming responses for immediate feedback
|
||||||
- Persistent history
|
- Persistent history
|
||||||
- Shell completions
|
- Shell completions
|
||||||
@ -77,9 +82,13 @@ grokkit/
|
|||||||
│ ├── logger.go # Logger setup + helpers
|
│ ├── logger.go # Logger setup + helpers
|
||||||
│ └── logger_test.go
|
│ └── logger_test.go
|
||||||
├── docs/ # Documentation
|
├── docs/ # Documentation
|
||||||
│ ├── TROUBLESHOOTING.md
|
│ └── developer-guide/ # Technical documentation
|
||||||
│ ├── ARCHITECTURE.md # This file
|
│ ├── ARCHITECTURE.md # This file
|
||||||
│ └── CONFIGURATION.md
|
│ ├── CONFIGURATION.md # Configuration guide
|
||||||
|
│ ├── TROUBLESHOOTING.md # Troubleshooting guide
|
||||||
|
│ └── index.md # Developer guide index
|
||||||
|
│ ├── user-guide/ # End-user documentation
|
||||||
|
│ └── index.md # Main documentation index
|
||||||
├── .gitea/workflows/ # CI/CD
|
├── .gitea/workflows/ # CI/CD
|
||||||
│ ├── ci.yml # Test + lint + build
|
│ ├── ci.yml # Test + lint + build
|
||||||
│ └── release.yml # Multi-platform releases
|
│ └── release.yml # Multi-platform releases
|
||||||
11
docs/developer-guide/index.md
Normal file
11
docs/developer-guide/index.md
Normal file
@ -0,0 +1,11 @@
|
|||||||
|
# Developer Guide
|
||||||
|
|
||||||
|
Welcome to the Grokkit Developer Guide. This section contains resources and guidelines for those who want to contribute to Grokkit's development or understand its internal workings.
|
||||||
|
|
||||||
|
## Resources
|
||||||
|
|
||||||
|
- **[Development Overview](overview.md)** — Build instructions, project structure, and the standard TODO workflow.
|
||||||
|
- **[Architecture Overview](ARCHITECTURE.md)** — Deep dive into the design principles, project structure, and technical implementation of Grokkit.
|
||||||
|
- **[Configuration Guide](CONFIGURATION.md)** — Detailed information on how to configure Grokkit via environment variables and config files.
|
||||||
|
- **[Troubleshooting](TROUBLESHOOTING.md)** — Common issues and their solutions encountered during development or deployment.
|
||||||
|
- **[Back to Documentation Index](../index.md)**
|
||||||
107
docs/developer-guide/overview.md
Normal file
107
docs/developer-guide/overview.md
Normal file
@ -0,0 +1,107 @@
|
|||||||
|
# 🛠️ Development Overview
|
||||||
|
|
||||||
|
This document provides a comprehensive overview of the development process for Grokkit, including build instructions, project structure, and the standard TODO workflow.
|
||||||
|
|
||||||
|
## Development
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# All tests pass without XAI_API_KEY (unit tests only)
|
||||||
|
|
||||||
|
# Run tests
|
||||||
|
make test
|
||||||
|
|
||||||
|
# Agent-specific tests
|
||||||
|
make test-agent
|
||||||
|
|
||||||
|
# Run tests with coverage report
|
||||||
|
make test-cover
|
||||||
|
open build/coverage.html
|
||||||
|
|
||||||
|
# Linting (matches CI, uses .golangci.yml config)
|
||||||
|
make lint
|
||||||
|
# Install golangci-lint if needed:
|
||||||
|
# go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
|
||||||
|
|
||||||
|
# Run specific tests
|
||||||
|
go test -run TestEditCommand ./cmd -v
|
||||||
|
|
||||||
|
# Build binary
|
||||||
|
make build
|
||||||
|
|
||||||
|
# Install locally
|
||||||
|
make install
|
||||||
|
|
||||||
|
# Clean build artifacts
|
||||||
|
make clean
|
||||||
|
```
|
||||||
|
|
||||||
|
### Project Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
grokkit/
|
||||||
|
├── cmd/ # CLI commands (Cobra)
|
||||||
|
│ ├── docs.go # grokkit docs — AI documentation generation
|
||||||
|
│ ├── lint.go # grokkit lint — AI-powered linting
|
||||||
|
│ ├── recipe.go # grokkit recipe — transactional recipe runner
|
||||||
|
│ ├── scaffold.go # grokkit scaffold — project-aware file generation
|
||||||
|
│ └── ... # chat, edit, commit, review, history, pr-describe, agent
|
||||||
|
├── config/ # Viper configuration
|
||||||
|
├── docs/ # Documentation
|
||||||
|
├── .grokkit/ # Project-local Grokkit data
|
||||||
|
│ └── recipes/ # Custom AI workflows (recipes)
|
||||||
|
├── todo/ # TODO tracking: queued/ (pending) and completed/ (historical record)
|
||||||
|
│ ├── queued/ # Pending TODO items
|
||||||
|
│ └── completed/ # Completed TODO items with history
|
||||||
|
├── internal/
|
||||||
|
│ ├── errors/ # Custom error types
|
||||||
|
│ ├── git/ # Git operations
|
||||||
|
│ ├── grok/ # xAI Grok API client
|
||||||
|
│ ├── linter/ # Multi-language linting
|
||||||
|
│ ├── logger/ # Structured slog logging
|
||||||
|
│ ├── recipe/ # Recipe loading and execution engine
|
||||||
|
│ └── version/ # Build/version info
|
||||||
|
├── main.go # Application entrypoint
|
||||||
|
├── go.mod # Dependencies
|
||||||
|
├── Makefile # Build automation
|
||||||
|
├── .golangci.yml # Golangci-lint configuration
|
||||||
|
└── scripts/ # Install scripts
|
||||||
|
```
|
||||||
|
|
||||||
|
## TODO Workflow
|
||||||
|
|
||||||
|
**Policy:**
|
||||||
|
From now on, the only thing to be committed directly to the `master` branch will be to-do items (.md files in `todo/queued/`).
|
||||||
|
|
||||||
|
**Process:**
|
||||||
|
1. When deciding to work on a to-do item: create a branch, implement on the branch, submit PR to `master`.
|
||||||
|
2. After PR merge: move the item to `todo/completed/`.
|
||||||
|
|
||||||
|
**Example workflow:**
|
||||||
|
```bash
|
||||||
|
git checkout -b feature/some-todo
|
||||||
|
# Implement changes, test with make test lint
|
||||||
|
git add .
|
||||||
|
git commit -m "feat: implement some-todo"
|
||||||
|
git push -u origin feature/some-todo
|
||||||
|
# Create and merge PR to master
|
||||||
|
|
||||||
|
# Post-merge:
|
||||||
|
git checkout master
|
||||||
|
git pull
|
||||||
|
mv "todo/queued/SOME_TODO.md" "todo/completed/SOME_TODO.md"
|
||||||
|
git add todo/
|
||||||
|
git commit -m "chore: complete some-todo"
|
||||||
|
git push origin master
|
||||||
|
```
|
||||||
|
|
||||||
|
### Gitea Actions Automation *(automates post-merge above)*
|
||||||
|
|
||||||
|
[`.gitea/workflows/auto-complete-todo.yml`](../../.gitea/workflows/auto-complete-todo.yml) triggers on PR `opened`/`synchronize`:
|
||||||
|
|
||||||
|
- Branches `feature/some-todo`: moves `todo/queued/some-todo.md` → `completed/`.
|
||||||
|
|
||||||
|
**One-time setup** (Gitea → Repo → Settings → Secrets & Variables → Actions):
|
||||||
|
- New Secret: `PAT_TOKEN` = [Personal Access Token](https://gitea.example.com/user/settings/tokens) (scope: `repo`).
|
||||||
|
- Optional: Branch protection → Require "Auto-complete TODO" status check.
|
||||||
|
|
||||||
|
**Result**: No manual post-merge steps needed!
|
||||||
24
docs/index.md
Normal file
24
docs/index.md
Normal file
@ -0,0 +1,24 @@
|
|||||||
|
# Grokkit Documentation
|
||||||
|
|
||||||
|
Welcome to the Grokkit documentation. Grokkit is a fast, native Go CLI that integrates Grok AI into your daily development and git workflows.
|
||||||
|
|
||||||
|
Whether you're looking for quick answers, AI-powered file editing, or complex multi-step automated workflows, Grokkit provides the tools to enhance your productivity.
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
|
||||||
|
- **[User Guide](user-guide/index.md)** — Comprehensive documentation for all Grokkit commands and features.
|
||||||
|
- **[Grokkit Workflows](user-guide/workflows.md)** — Learn how to integrate Grokkit into your development cycle effectively.
|
||||||
|
- **[Safety & Change Management](user-guide/safety.md)** — Learn how Grokkit integrates with Git to keep your codebase stable and safe.
|
||||||
|
- **[Configuration Guide](developer-guide/CONFIGURATION.md)** — Detailed information on how to configure Grokkit via environment variables and config files.
|
||||||
|
- **[Developer Guide](developer-guide/index.md)** — Resources and guidelines for contributing to Grokkit development.
|
||||||
|
- **[Development Overview](developer-guide/overview.md)** — Build instructions, project structure, and the standard TODO workflow.
|
||||||
|
- **[Architecture Overview](developer-guide/ARCHITECTURE.md)** — Deep dive into the design principles, project structure, and technical implementation of Grokkit.
|
||||||
|
- **[Troubleshooting](developer-guide/TROUBLESHOOTING.md)** — Common issues and their solutions.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Quick Links
|
||||||
|
|
||||||
|
- [Grokkit Repository](https://repos.gmgauthier.com/gmgauthier/grokkit)
|
||||||
|
- [Grokkit Releases](https://repos.gmgauthier.com/gmgauthier/grokkit/releases)
|
||||||
|
- [Main README](../README.md)
|
||||||
49
docs/user-guide/agent.md
Normal file
49
docs/user-guide/agent.md
Normal file
@ -0,0 +1,49 @@
|
|||||||
|
# 🤖 Agent Guide
|
||||||
|
|
||||||
|
The `agent` command is a multi-file autonomous agent that allows you to perform complex refactorings or feature implementations across multiple files using natural language instructions.
|
||||||
|
|
||||||
|
> [!WARNING]
|
||||||
|
> This command is currently experimental. Always ensure you have a clean git state before running the agent.
|
||||||
|
|
||||||
|
### Why use Agent?
|
||||||
|
|
||||||
|
- **Multi-file awareness**: Unlike the `edit` command, the `agent` command scans your project to understand the context and identifies which files need to be changed.
|
||||||
|
- **Autonomous Planning**: Grok generates a high-level plan for the entire task before proposing any code changes.
|
||||||
|
- **Interactive Execution**: You review the plan first, then review and approve changes for each file individually or all at once.
|
||||||
|
- **Project-wide Refactoring**: Ideal for tasks like "refactor authentication to use JWT" or "add a new field to the User struct across all layers".
|
||||||
|
|
||||||
|
### Usage
|
||||||
|
|
||||||
|
Multi-file agent for complex refactoring (experimental).
|
||||||
|
|
||||||
|
```bash
|
||||||
|
grokkit agent "refactor authentication to use JWT"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Options
|
||||||
|
|
||||||
|
| Flag | Description |
|
||||||
|
|------|-------------|
|
||||||
|
| `--model`, `-m` | Override the default model (e.g., `grok-4`) |
|
||||||
|
|
||||||
|
### Workflow
|
||||||
|
|
||||||
|
1. **Project Scan**: The agent scans the current directory for relevant files (currently focused on `.go` files).
|
||||||
|
2. **Plan Generation**: Grok analyzes your instruction and the file list to create a step-by-step plan.
|
||||||
|
3. **Plan Review**: You review the proposed plan and decide whether to proceed.
|
||||||
|
4. **Iterative Editing**:
|
||||||
|
- For each file in the plan, Grok generates the updated content.
|
||||||
|
- You see a diff-style preview of the proposed changes for that specific file.
|
||||||
|
- You can choose to:
|
||||||
|
- `y`: Apply changes to this file and move to the next.
|
||||||
|
- `n`: Skip changes for this file and move to the next.
|
||||||
|
- `a`: Apply changes to this file and all remaining files in the plan without further confirmation.
|
||||||
|
5. **Completion**: Once all files are processed, the agent provides a summary of the actions taken.
|
||||||
|
|
||||||
|
### Safety & Best Practices
|
||||||
|
|
||||||
|
- **Clean Git State**: Always run the agent on a clean git branch. This allows you to easily `git reset --hard` or `git restore` if the AI makes undesired changes.
|
||||||
|
- **Review the Plan**: Pay close attention to the initial plan. If it seems off, abort and try again with a more specific instruction.
|
||||||
|
- **Incremental Approval**: For complex tasks, approve files one by one (`y`) rather than using the "apply all" (`a`) option.
|
||||||
|
- **Verify Results**: After the agent finishes, run your tests (`make test`) and linter (`make lint`) to ensure the changes are correct and follow project standards.
|
||||||
|
- **Specific Instructions**: Provide as much context as possible in your instruction to help the agent understand the scope of the change.
|
||||||
51
docs/user-guide/changelog.md
Normal file
51
docs/user-guide/changelog.md
Normal file
@ -0,0 +1,51 @@
|
|||||||
|
# 🗒️ Changelog Guide
|
||||||
|
|
||||||
|
The `changelog` command automatically generates a `CHANGELOG.md` section based on your git history. It's designed to create professional, categorized changelogs that can be used directly for releases.
|
||||||
|
|
||||||
|
### Key Features
|
||||||
|
|
||||||
|
- **Categorized Changes**: Automatically groups commits into `Added`, `Changed`, and `Fixed`.
|
||||||
|
- **Gitea Compatible**: The output is formatted for easy pasting into Gitea release notes.
|
||||||
|
- **Project Maintenance**: Automatically updates your existing `CHANGELOG.md` file.
|
||||||
|
- **Smart Summaries**: Grok creates concise, imperative bullet points for each change.
|
||||||
|
|
||||||
|
### Usage
|
||||||
|
|
||||||
|
Generate a clean `CHANGELOG.md` section from git history, designed specifically so the output can be pasted directly into Gitea release notes.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. Create your version tag first
|
||||||
|
git tag v0.2.0
|
||||||
|
|
||||||
|
# 2. Generate preview + write (with safety confirmation)
|
||||||
|
grokkit changelog
|
||||||
|
|
||||||
|
# 3. Output ONLY the new section (perfect for Gitea "Release notes")
|
||||||
|
grokkit changelog --stdout
|
||||||
|
|
||||||
|
# 4. Write file + get commit reminder
|
||||||
|
grokkit changelog --commit
|
||||||
|
```
|
||||||
|
|
||||||
|
### Options
|
||||||
|
|
||||||
|
| Flag | Description |
|
||||||
|
|------|-------------|
|
||||||
|
| `--since` | Start from this tag/ref (default: previous tag) |
|
||||||
|
| `--version`, `-V` | Override the version number for the header (default: latest git tag) |
|
||||||
|
| `--stdout` | Print ONLY the new section (useful for pasting into release notes) |
|
||||||
|
| `--commit` | Reminds you to commit the changes after updating the file |
|
||||||
|
| `--model`, `-m` | Override the default model (e.g., `grok-4`) |
|
||||||
|
|
||||||
|
### How it Works
|
||||||
|
|
||||||
|
1. **History Retrieval**: Grokkit finds the commits since the last tag.
|
||||||
|
2. **Categorization**: It sends the commit history to Grok to be categorized and summarized.
|
||||||
|
3. **Markdown Generation**: Grok returns a formatted markdown section.
|
||||||
|
4. **File Update**: Grokkit prepends the new section to your `CHANGELOG.md` or creates it if it doesn't exist.
|
||||||
|
|
||||||
|
### Best Practices
|
||||||
|
|
||||||
|
- **Conventional Commits**: Use conventional commit messages to help the AI categorize changes more accurately.
|
||||||
|
- **Use tags**: Ensure your project uses git tags so Grokkit can correctly identify the changes since the last version.
|
||||||
|
- **Review before writing**: Always review the proposed changelog update before confirming.
|
||||||
45
docs/user-guide/chat.md
Normal file
45
docs/user-guide/chat.md
Normal file
@ -0,0 +1,45 @@
|
|||||||
|
# 💬 Chat Guide
|
||||||
|
|
||||||
|
The `chat` command starts a full interactive session with Grok. Unlike other commands that are one-shot, `chat` maintains a conversation history, allowing for multi-turn dialogues and context-aware responses.
|
||||||
|
|
||||||
|
### Key Features
|
||||||
|
|
||||||
|
- **Interactive**: Real-time conversation with Grok.
|
||||||
|
- **Streaming**: Responses are streamed to your terminal as they are generated.
|
||||||
|
- **History**: Grokkit automatically saves and reloads your chat history from `~/.config/grokkit/chat_history.json`.
|
||||||
|
- **System Prompt**: Grok is configured with a project-aware system prompt to provide relevant answers.
|
||||||
|
|
||||||
|
### Usage
|
||||||
|
|
||||||
|
```bash
|
||||||
|
grokkit chat # Start chat session
|
||||||
|
grokkit chat -m grok-beta # Use specific model
|
||||||
|
grokkit chat --debug # Enable debug logging
|
||||||
|
```
|
||||||
|
|
||||||
|
### Tips
|
||||||
|
|
||||||
|
- Type `/quit`, `/q`, or `exit` to exit
|
||||||
|
- History is saved automatically between sessions
|
||||||
|
- Use `--debug` to see API request timing
|
||||||
|
|
||||||
|
### Commands within Chat
|
||||||
|
|
||||||
|
- `/quit` or `/q`: Exit the chat session.
|
||||||
|
- `exit`: Exit the chat session.
|
||||||
|
- `Ctrl+C`: Exit the chat session.
|
||||||
|
|
||||||
|
### Options
|
||||||
|
|
||||||
|
| Flag | Description |
|
||||||
|
|------|-------------|
|
||||||
|
| `--model`, `-m` | Override the default model (e.g., `grok-4`) |
|
||||||
|
|
||||||
|
### Configuration
|
||||||
|
|
||||||
|
You can configure the location of the history file in your `config.toml`:
|
||||||
|
|
||||||
|
```toml
|
||||||
|
[chat]
|
||||||
|
history_file = "~/.config/grokkit/my_custom_history.json"
|
||||||
|
```
|
||||||
62
docs/user-guide/commit-msg.md
Normal file
62
docs/user-guide/commit-msg.md
Normal file
@ -0,0 +1,62 @@
|
|||||||
|
# 📝 Commit Message Guide
|
||||||
|
|
||||||
|
The `commit-msg` command generates a conventional commit message based on your currently staged changes. Unlike the `commit` command, it only outputs the suggested message without actually performing the git commit.
|
||||||
|
|
||||||
|
### Why use Commit Message?
|
||||||
|
|
||||||
|
- **Consistency**: Automatically generate messages following the [Conventional Commits](https://www.conventionalcommits.org/) specification (e.g., `feat(api): add JWT authentication`).
|
||||||
|
- **Convenience**: Quickly get a descriptive summary of your changes without manually reviewing the diff.
|
||||||
|
- **Workflow flexibility**: Useful when you want to review, edit, or use the generated message in a custom git command or GUI.
|
||||||
|
|
||||||
|
### Basic Usage
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git add .
|
||||||
|
grokkit commit-msg # Generate message only
|
||||||
|
grokkit commit-msg -m grok-4 # Use specific model
|
||||||
|
```
|
||||||
|
|
||||||
|
**Output format:** `type(scope): subject\n\nbody`
|
||||||
|
|
||||||
|
### Options
|
||||||
|
|
||||||
|
| Flag | Description |
|
||||||
|
|------|-------------|
|
||||||
|
| `--model`, `-m` | Override the default model (e.g., `grok-4`) |
|
||||||
|
|
||||||
|
### How it Works
|
||||||
|
|
||||||
|
1. **Diff Retrieval**: Grokkit runs `git diff --cached --no-color` to get all staged changes.
|
||||||
|
2. **AI Analysis**: It sends the diff to Grok with instructions to generate a conventional commit message.
|
||||||
|
3. **Streaming Output**: The generated message is streamed directly to your terminal.
|
||||||
|
|
||||||
|
### Workflow Example
|
||||||
|
|
||||||
|
1. Stage your changes:
|
||||||
|
```bash
|
||||||
|
git add main.go internal/grok/client.go
|
||||||
|
```
|
||||||
|
2. Generate the message:
|
||||||
|
```bash
|
||||||
|
grokkit commit-msg
|
||||||
|
```
|
||||||
|
3. Use the output to commit:
|
||||||
|
```bash
|
||||||
|
git commit -m "$(grokkit commit-msg)"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Comparison with `commit` command
|
||||||
|
|
||||||
|
| Feature | `commit-msg` | `commit` |
|
||||||
|
|---------|--------------|----------|
|
||||||
|
| Generates AI message | Yes | Yes |
|
||||||
|
| Shows diff-based summary | Yes | Yes |
|
||||||
|
| Asks for confirmation | No | Yes |
|
||||||
|
| Performs `git commit` | No | Yes |
|
||||||
|
| Use case | Scripting / Manual control | Interactive git workflow |
|
||||||
|
|
||||||
|
### Best Practices
|
||||||
|
|
||||||
|
- **Stage only related changes**: To get the most accurate commit message, stage only the changes that belong to a single logical unit of work.
|
||||||
|
- **Review the output**: AI-generated messages are usually good but may need minor tweaks for complex changes.
|
||||||
|
- **Model Choice**: Use a reasoning model (`grok-4`) for complex architectural changes to get more detailed body descriptions in the commit message.
|
||||||
58
docs/user-guide/commit.md
Normal file
58
docs/user-guide/commit.md
Normal file
@ -0,0 +1,58 @@
|
|||||||
|
# ✅ Commit Guide
|
||||||
|
|
||||||
|
Grokkit provides two commands to help you generate high-quality, conventional commit messages from your staged changes: `commit-msg` and `commit`.
|
||||||
|
|
||||||
|
### Commit-msg
|
||||||
|
|
||||||
|
The `commit-msg` command generates a conventional commit message based on your currently staged changes (`git add`). It's perfect for when you want to review the message before using it in your commit.
|
||||||
|
|
||||||
|
#### Usage
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git add .
|
||||||
|
grokkit commit-msg
|
||||||
|
```
|
||||||
|
|
||||||
|
**Output Example:**
|
||||||
|
```text
|
||||||
|
feat(git): add support for custom commit message templates
|
||||||
|
|
||||||
|
Implemented a new system for defining custom templates for commit messages, allowing for project-specific conventions.
|
||||||
|
```
|
||||||
|
|
||||||
|
### Commit
|
||||||
|
|
||||||
|
The `commit` command generates a commit message and commits in one step.
|
||||||
|
|
||||||
|
#### Usage
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git add .
|
||||||
|
grokkit commit # Generate + confirm + commit
|
||||||
|
```
|
||||||
|
|
||||||
|
**Interactive Workflow:**
|
||||||
|
1. Grokkit analyzes your staged changes.
|
||||||
|
2. It generates a conventional commit message.
|
||||||
|
3. It shows you the proposed message.
|
||||||
|
4. It asks for confirmation: `Commit with this message? (y/n): `.
|
||||||
|
5. If you confirm, it runs `git commit -m "<message>"`.
|
||||||
|
|
||||||
|
### Why use AI for Commits?
|
||||||
|
|
||||||
|
- **Conventional Format**: Automatically follows the `type(scope): subject` format.
|
||||||
|
- **Accurate Descriptions**: Grok analyzes the actual diff to provide a meaningful summary of your changes.
|
||||||
|
- **Consistency**: Ensures that all commit messages in your project follow the same high standard.
|
||||||
|
- **Save Time**: No more staring at a blank screen trying to remember everything you changed.
|
||||||
|
|
||||||
|
### Options
|
||||||
|
|
||||||
|
| Flag | Description |
|
||||||
|
|------|-------------|
|
||||||
|
| `--model`, `-m` | Override the default model (e.g., `grok-4`) |
|
||||||
|
|
||||||
|
### Best Practices
|
||||||
|
|
||||||
|
- **Stage only relevant changes**: For the best commit message, only stage the changes that belong in a single commit.
|
||||||
|
- **Review before committing**: Always read the generated message to ensure it accurately reflects your intent.
|
||||||
|
- **Model selection**: For complex changes, use a more powerful model like `grok-4` to get a better summary.
|
||||||
42
docs/user-guide/completion.md
Normal file
42
docs/user-guide/completion.md
Normal file
@ -0,0 +1,42 @@
|
|||||||
|
# Completion Guide
|
||||||
|
|
||||||
|
The `completion` command generates shell completion scripts for Grokkit, making it faster and easier to use the CLI by providing tab-completion for commands and flags.
|
||||||
|
|
||||||
|
### Supported Shells
|
||||||
|
|
||||||
|
- **Bash**
|
||||||
|
- **Zsh**
|
||||||
|
- **Fish**
|
||||||
|
- **PowerShell**
|
||||||
|
|
||||||
|
### Installation
|
||||||
|
|
||||||
|
To enable completions, you need to generate the script for your shell and source it.
|
||||||
|
|
||||||
|
#### Bash
|
||||||
|
|
||||||
|
```bash
|
||||||
|
grokkit completion bash | sudo tee /etc/bash_completion.d/grokkit
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Zsh (oh-my-zsh)
|
||||||
|
|
||||||
|
```zsh
|
||||||
|
grokkit completion zsh > ~/.oh-my-zsh/completions/_grokkit
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Fish
|
||||||
|
|
||||||
|
```fish
|
||||||
|
grokkit completion fish > ~/.config/fish/completions/grokkit.fish
|
||||||
|
```
|
||||||
|
|
||||||
|
#### PowerShell
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
grokkit completion powershell | Out-String | Invoke-Expression
|
||||||
|
```
|
||||||
|
|
||||||
|
### Usage
|
||||||
|
|
||||||
|
Once installed, you can simply type `grokkit ` followed by `Tab` to see available commands, or `grokkit <command> --` followed by `Tab` to see available flags.
|
||||||
60
docs/user-guide/docs.md
Normal file
60
docs/user-guide/docs.md
Normal file
@ -0,0 +1,60 @@
|
|||||||
|
# 📖 Docs Guide
|
||||||
|
|
||||||
|
The `docs` command uses AI to generate language-appropriate documentation comments for your source files. It supports a wide range of programming languages and documentation styles.
|
||||||
|
|
||||||
|
### Usage
|
||||||
|
|
||||||
|
Generate language-appropriate documentation comments using Grok AI.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Preview and confirm
|
||||||
|
grokkit docs main.go
|
||||||
|
|
||||||
|
# Auto-apply without confirmation
|
||||||
|
grokkit docs handlers.go models.go --auto-apply
|
||||||
|
|
||||||
|
# Document multiple files at once
|
||||||
|
grokkit docs cmd/*.go --auto-apply
|
||||||
|
|
||||||
|
# Use specific model
|
||||||
|
grokkit docs app.py -m grok-4
|
||||||
|
```
|
||||||
|
|
||||||
|
### Supported doc styles by language
|
||||||
|
|
||||||
|
| Language | Style |
|
||||||
|
|----------|-------|
|
||||||
|
| Go | godoc (`// FuncName does...`) |
|
||||||
|
| Python | PEP 257 docstrings (`"""Summary\n\nArgs:..."""`) |
|
||||||
|
| C / C++ | Doxygen (`/** @brief ... @param ... @return ... */`) |
|
||||||
|
| JavaScript / TypeScript | JSDoc (`/** @param {type} name ... */`) |
|
||||||
|
| Rust | rustdoc (`/// Summary\n/// # Arguments`) |
|
||||||
|
| Ruby | YARD (`# @param [Type] name`) |
|
||||||
|
| Java | Javadoc (`/** @param ... @return ... */`) |
|
||||||
|
| Shell | Shell comments (`# function: desc, # Args: ...`) |
|
||||||
|
|
||||||
|
### Safety features
|
||||||
|
|
||||||
|
- Shows first 50 lines of documented code as preview
|
||||||
|
- Requires confirmation (unless `--auto-apply`)
|
||||||
|
|
||||||
|
### Options
|
||||||
|
|
||||||
|
| Flag | Description |
|
||||||
|
|------|-------------|
|
||||||
|
| `--auto-apply` | Apply documentation without confirmation |
|
||||||
|
| `--model`, `-m` | Override the default model (e.g., `grok-4`) |
|
||||||
|
|
||||||
|
### How it Works
|
||||||
|
|
||||||
|
1. **Language Detection**: Grokkit detects the language of each file to select the appropriate documentation style.
|
||||||
|
2. **Contextual Analysis**: It reads the file and prepares a prompt for Grok.
|
||||||
|
3. **AI Generation**: Grok generates the documentation comments for all public functions, methods, and types.
|
||||||
|
4. **Interactive Preview**: Grokkit shows you a preview of the documented code.
|
||||||
|
5. **Confirmation**: You review and confirm before the changes are applied to your file (unless you use `--auto-apply`).
|
||||||
|
|
||||||
|
### Best Practices
|
||||||
|
|
||||||
|
- **Document public APIs**: Use `docs` to ensure your project's public interface is well-documented.
|
||||||
|
- **Review for Accuracy**: Always read the generated documentation to ensure it accurately reflects the function's purpose and behavior.
|
||||||
|
- **Use for complex code**: For particularly complex functions, AI-generated documentation can be very helpful for clarifying logic.
|
||||||
53
docs/user-guide/edit.md
Normal file
53
docs/user-guide/edit.md
Normal file
@ -0,0 +1,53 @@
|
|||||||
|
# ✏️ Edit Guide
|
||||||
|
|
||||||
|
The `edit` command allows you to modify an existing file in-place using natural language instructions. It's a quick and efficient way to refactor code, fix bugs, or add features without manually editing the file.
|
||||||
|
|
||||||
|
### Why use Edit?
|
||||||
|
|
||||||
|
- **Natural Language**: Just tell Grok what you want to change (e.g., "Add a new parameter to the `NewClient` function").
|
||||||
|
- **Interactive Preview**: See the proposed changes in a unified diff format before they are applied.
|
||||||
|
- **Refactoring made easy**: Effortlessly refactor large functions or rewrite entire blocks of code.
|
||||||
|
- **Cleanup**: `edit` automatically removes unnecessary comments, last modified timestamps, and ownership headers for a cleaner codebase.
|
||||||
|
|
||||||
|
### Basic Usage
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Basic usage
|
||||||
|
grokkit edit main.go "add error handling to all functions"
|
||||||
|
|
||||||
|
# Complex refactoring
|
||||||
|
grokkit edit server.go "convert this to use context for cancellation"
|
||||||
|
|
||||||
|
# Add features
|
||||||
|
grokkit edit api.go "add rate limiting middleware"
|
||||||
|
|
||||||
|
# Documentation
|
||||||
|
grokkit edit utils.go "add detailed docstrings to all exported functions"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Safety Features
|
||||||
|
|
||||||
|
- **Diff-style Preview**: Shows exactly what will change.
|
||||||
|
- **Confirmation Required**: Nothing is written without your `y/N`.
|
||||||
|
- **Silent Streaming**: No console spam while waiting.
|
||||||
|
|
||||||
|
### Options
|
||||||
|
|
||||||
|
| Flag | Description |
|
||||||
|
|------|-------------|
|
||||||
|
| `--model`, `-m` | Override the default model (e.g., `grok-4`) |
|
||||||
|
|
||||||
|
### How it Works
|
||||||
|
|
||||||
|
1. **File Retrieval**: Grokkit reads the content of the target file.
|
||||||
|
2. **Contextual Analysis**: It prepares a prompt for Grok with the original file content and your instructions.
|
||||||
|
3. **AI Generation**: Grok processes the request and returns the updated file content.
|
||||||
|
4. **Interactive Preview**: Grokkit shows you a preview of the changes in a unified diff format.
|
||||||
|
5. **Confirmation**: You review the changes and confirm before the file is overwritten.
|
||||||
|
|
||||||
|
### Best Practices
|
||||||
|
|
||||||
|
- **Specific Instructions**: The more specific you are, the better the result. Instead of "Fix the bug", try "Fix the race condition in the `UpdateState` method".
|
||||||
|
- **Review carefully**: Always review the diff before applying changes, especially for complex refactors.
|
||||||
|
- **Git workflow**: Commit your changes before using `edit` so you can easily revert if you're not happy with the result.
|
||||||
|
- **Combine with Lint**: After editing, run `grokkit lint` to ensure the new code meets your project's standards.
|
||||||
33
docs/user-guide/history.md
Normal file
33
docs/user-guide/history.md
Normal file
@ -0,0 +1,33 @@
|
|||||||
|
# 📜 History Guide
|
||||||
|
|
||||||
|
The `history` command provides a concise, AI-generated summary of your recent git history. It analyzes the last 10 commits to give you a high-level overview of recent developments.
|
||||||
|
|
||||||
|
### Key Features
|
||||||
|
|
||||||
|
- **Quick Summaries**: Get a quick catch-up on what's been happening in the repo.
|
||||||
|
- **AI-Powered Analysis**: Grok translates individual commit messages into 3-5 high-level bullet points.
|
||||||
|
- **Fast and Efficient**: A one-shot command for immediate results.
|
||||||
|
|
||||||
|
### Usage
|
||||||
|
|
||||||
|
```bash
|
||||||
|
grokkit history # Last 10 commits
|
||||||
|
```
|
||||||
|
|
||||||
|
### Options
|
||||||
|
|
||||||
|
| Flag | Description |
|
||||||
|
|------|-------------|
|
||||||
|
| `--model`, `-m` | Override the default model (e.g., `grok-4`) |
|
||||||
|
|
||||||
|
### How it Works
|
||||||
|
|
||||||
|
1. **Commit Log**: Grokkit runs `git log --oneline -10` to get the 10 most recent commits.
|
||||||
|
2. **AI Analysis**: It sends this log to Grok with a prompt to summarize the history.
|
||||||
|
3. **Bullet Point Summary**: Grok returns a 3-5 point summary of the most important changes.
|
||||||
|
|
||||||
|
### When to use History
|
||||||
|
|
||||||
|
- **Catching up**: Use `history` after pulling from the remote to see what's changed.
|
||||||
|
- **Branch review**: Use it to quickly recall what you've worked on recently.
|
||||||
|
- **Project overview**: Great for getting a quick status update on a project you haven't touched in a few days.
|
||||||
52
docs/user-guide/index.md
Normal file
52
docs/user-guide/index.md
Normal file
@ -0,0 +1,52 @@
|
|||||||
|
# Grokkit User's Guide
|
||||||
|
|
||||||
|
Welcome to the full user documentation for **Grokkit** — a fast, native Go CLI for Grok that supercharges your coding workflow.
|
||||||
|
|
||||||
|
## Quick Navigation
|
||||||
|
|
||||||
|
### 🛡️ Safety & Change Management
|
||||||
|
- **[Safety & Change Management](safety.md)** — Learn how Grokkit integrates with Git to keep your codebase stable and safe.
|
||||||
|
|
||||||
|
### 🔄 Workflows
|
||||||
|
- **[Grokkit Workflows](workflows.md)** — Learn how to integrate Grokkit into your development cycle effectively.
|
||||||
|
|
||||||
|
### Core Commands
|
||||||
|
- **[👨🍳 Recipe](recipe.md)** — The star of the show. Run powerful, transactional, multi-step LLM workflows defined in simple markdown files.
|
||||||
|
- **[🤖 Agent](agent.md)** — Multi-file agent for complex refactorings and project-wide changes.
|
||||||
|
- **[🏗️ Scaffold](scaffold.md)** — Safely generate new files with Grok preview + confirmation.
|
||||||
|
- **[🧪 Testgen](testgen.md)** — Generate high-quality unit tests for Go, Python, C/C++, etc.
|
||||||
|
- **[✏️ Edit](edit.md)** — In-place file editing with Grok (safe preview mode).
|
||||||
|
|
||||||
|
### Git Workflow Commands
|
||||||
|
- **[✅ Commit](commit.md)** — AI-powered conventional commit messages with direct git commit.
|
||||||
|
- **[📝 Commit-Msg](commit-msg.md)** — Generate AI-suggested conventional commit messages.
|
||||||
|
- **[🗒️ Changelog](changelog.md)** — Generate CHANGELOG.md from git history.
|
||||||
|
- **[📋 PR-Describe](pr-describe.md)** — Generate full PR descriptions.
|
||||||
|
- **[📜 History](history.md)** — Summarize recent git history.
|
||||||
|
|
||||||
|
### Other Useful Commands
|
||||||
|
- **[💬 Chat](chat.md)** — Full interactive chat with history and streaming
|
||||||
|
- **[🤖 Query](query.md)** — One-shot programming-focused queries
|
||||||
|
- **[🔍 Review](review.md)** — AI code review of the current repo/directory
|
||||||
|
- **[🔧 Lint](lint.md)** — Lint + AI-suggested fixes
|
||||||
|
- **[📖 Docs](docs.md)** — Generate documentation comments
|
||||||
|
- **[Completion](completion.md)** — Generate shell completion scripts
|
||||||
|
- **[🏷️ Version](version.md)** — Print version information
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Getting Started
|
||||||
|
|
||||||
|
See the [main README](../README.md) for installation and basic usage.
|
||||||
|
|
||||||
|
See the [Configuration Guide](../developer-guide/CONFIGURATION.md) for detailed information on how to configure Grokkit via environment variables and config files.
|
||||||
|
|
||||||
|
Want to dive deep? Start with the **[Recipe Guide](recipe.md)** — it's the most powerful and unique feature of Grokkit.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Contributing to the Docs
|
||||||
|
|
||||||
|
Found something missing or unclear? Feel free to open a PR or issue on the repo.
|
||||||
|
|
||||||
|
Happy hacking!
|
||||||
52
docs/user-guide/lint.md
Normal file
52
docs/user-guide/lint.md
Normal file
@ -0,0 +1,52 @@
|
|||||||
|
# 🔧 Lint Guide
|
||||||
|
|
||||||
|
The `lint` command is an AI-powered linter that identifies issues in your code and optionally provides AI-suggested fixes. It's designed to work with multiple languages and provide actionable suggestions.
|
||||||
|
|
||||||
|
### Key Features
|
||||||
|
|
||||||
|
- **Multi-language Support**: Automatically detects and lints Go, Python, C/C++, JS/TS, Rust, and more.
|
||||||
|
- **AI-Suggested Fixes**: Not only finds issues but can also suggest how to fix them.
|
||||||
|
- **Interactive Preview**: See the proposed fixes in a diff format before applying them.
|
||||||
|
- **Clean Code**: Grok is instructed to provide minimal, idiomatic fixes that match your project's style.
|
||||||
|
|
||||||
|
### Usage
|
||||||
|
|
||||||
|
Automatically detect language, run linter, and apply AI-suggested fixes.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Just check for issues (no fixes)
|
||||||
|
grokkit lint main.go --dry-run
|
||||||
|
|
||||||
|
# Interactive fix (preview + confirmation)
|
||||||
|
grokkit lint app.py
|
||||||
|
|
||||||
|
# Auto-fix without confirmation
|
||||||
|
grokkit lint server.js --auto-fix
|
||||||
|
|
||||||
|
# Use specific model
|
||||||
|
grokkit lint script.rb -m grok-4
|
||||||
|
```
|
||||||
|
|
||||||
|
### Supported languages
|
||||||
|
|
||||||
|
- **Go** (golangci-lint, go vet)
|
||||||
|
- **Python** (pylint, flake8, ruff)
|
||||||
|
- **JavaScript/JSX** (eslint)
|
||||||
|
- **TypeScript/TSX** (eslint, tsc)
|
||||||
|
- **Rust** (clippy)
|
||||||
|
- **Ruby** (rubocop)
|
||||||
|
- **Java** (checkstyle)
|
||||||
|
- **C/C++** (clang-tidy)
|
||||||
|
- **Shell** (shellcheck)
|
||||||
|
|
||||||
|
### Safety features
|
||||||
|
|
||||||
|
- Shows preview of fixes
|
||||||
|
- Verifies fixes by re-running linter
|
||||||
|
- Requires confirmation (unless `--auto-fix`)
|
||||||
|
|
||||||
|
### Best Practices
|
||||||
|
|
||||||
|
- **Lint early and often**: Catching issues early is much easier than fixing them later.
|
||||||
|
- **Review fixes carefully**: AI-suggested fixes are usually excellent, but always review them to ensure they align with your project's specific requirements.
|
||||||
|
- **Combine with Review**: Use `lint` for basic issues and `grokkit review` for deeper logic analysis.
|
||||||
49
docs/user-guide/pr-describe.md
Normal file
49
docs/user-guide/pr-describe.md
Normal file
@ -0,0 +1,49 @@
|
|||||||
|
# 📋 PR-Describe Guide
|
||||||
|
|
||||||
|
The `pr-describe` command generates a professional Pull Request title and a detailed body by analyzing the diff between your current branch and a base branch.
|
||||||
|
|
||||||
|
### Key Features
|
||||||
|
|
||||||
|
- **Automated PR Descriptions**: Saves time by drafting the entire PR description for you.
|
||||||
|
- **Context-Aware**: Analyzes every change on your branch to explain the "what" and "why."
|
||||||
|
- **Professional Format**: Includes sections for changes, motivation, and testing notes.
|
||||||
|
- **Customizable Base**: Compare against any branch (defaults to `master`).
|
||||||
|
|
||||||
|
### Usage
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# From current branch vs master
|
||||||
|
grokkit pr-describe
|
||||||
|
|
||||||
|
# Compare against a specific base branch
|
||||||
|
grokkit pr-describe --base main
|
||||||
|
|
||||||
|
# With specific model
|
||||||
|
grokkit pr-describe -m grok-4
|
||||||
|
```
|
||||||
|
|
||||||
|
**Output includes:**
|
||||||
|
- Title suggestion
|
||||||
|
- Summary of changes
|
||||||
|
- Motivation/context
|
||||||
|
- Testing notes
|
||||||
|
|
||||||
|
### Options
|
||||||
|
|
||||||
|
| Flag | Description |
|
||||||
|
|------|-------------|
|
||||||
|
| `--base`, `-b` | Base branch to compare against (default: `master`) |
|
||||||
|
| `--model`, `-m` | Override the default model (e.g., `grok-4`) |
|
||||||
|
|
||||||
|
### How it Works
|
||||||
|
|
||||||
|
1. **Diff Generation**: Grokkit runs `git diff <base>..HEAD` to identify all changes on your current branch.
|
||||||
|
2. **AI Analysis**: It sends the full diff to Grok with a specialized prompt for PR generation.
|
||||||
|
3. **Structured Output**: Grok returns a professional PR title and body.
|
||||||
|
4. **Streaming Results**: You see the description as it's being generated.
|
||||||
|
|
||||||
|
### Best Practices
|
||||||
|
|
||||||
|
- **Keep branches focused**: PR descriptions are most effective when the branch addresses a single feature or fix.
|
||||||
|
- **Review and edit**: Use the AI-generated description as a strong starting point, then add any specific internal context or links (e.g., Jira tickets).
|
||||||
|
- **Model selection**: For large PRs with many changes, use a more powerful model like `grok-4` for a better high-level summary.
|
||||||
38
docs/user-guide/query.md
Normal file
38
docs/user-guide/query.md
Normal file
@ -0,0 +1,38 @@
|
|||||||
|
# 🤖 Query Guide
|
||||||
|
|
||||||
|
The `query` command is a one-shot, non-interactive interface for asking Grok programming-focused questions. It's ideal for quick inquiries where you don't need a full chat history.
|
||||||
|
|
||||||
|
### Why use Query?
|
||||||
|
|
||||||
|
- **Fast**: Get a direct answer to a single question.
|
||||||
|
- **Minimalist**: No chat history or context overhead.
|
||||||
|
- **Focused**: Perfect for "How do I do X in Go?" or "Explain this regex."
|
||||||
|
|
||||||
|
### Usage
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Basic usage
|
||||||
|
grokkit query "How do I sort a slice of structs by a field in Go?"
|
||||||
|
|
||||||
|
# Longer, more detailed answer
|
||||||
|
grokkit query --wordy "Explain how Go's context package works with cancellation"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Features
|
||||||
|
|
||||||
|
- **Default mode** is concise, factual, and actionable.
|
||||||
|
- **`--wordy` flag** gives longer, more explanatory answers.
|
||||||
|
- **Fast model** used by default for speed (non-reasoning).
|
||||||
|
- **No persistent history** or interactive chat UI.
|
||||||
|
|
||||||
|
### Options
|
||||||
|
|
||||||
|
| Flag | Description |
|
||||||
|
|------|-------------|
|
||||||
|
| `--wordy` | Give a longer, more detailed answer |
|
||||||
|
| `--model`, `-m` | Override the default model (e.g., `grok-4`) |
|
||||||
|
|
||||||
|
### When to use Query vs. Chat
|
||||||
|
|
||||||
|
- Use **Query** for simple, independent questions that don't require follow-up.
|
||||||
|
- Use **Chat** when you need to have a back-and-forth conversation or want Grok to remember previous context.
|
||||||
102
docs/user-guide/recipe.md
Normal file
102
docs/user-guide/recipe.md
Normal file
@ -0,0 +1,102 @@
|
|||||||
|
# 👨🍳 Recipe Guide
|
||||||
|
|
||||||
|
The `recipe` command is the most powerful feature in Grokkit. It lets you define sophisticated, multi-step, transactional workflows that Grok executes step-by-step with full transparency and user approval.
|
||||||
|
|
||||||
|
### What is a Recipe?
|
||||||
|
|
||||||
|
A recipe is a plain markdown file (`.md`) that lives in:
|
||||||
|
- `.grokkit/recipes/` (project-local, preferred)
|
||||||
|
- `~/.local/share/grokkit/recipes/` (global)
|
||||||
|
|
||||||
|
Each recipe contains:
|
||||||
|
- YAML frontmatter (metadata + parameters)
|
||||||
|
- Clear, numbered steps written in natural language
|
||||||
|
- Optional final summary
|
||||||
|
|
||||||
|
### Usage
|
||||||
|
|
||||||
|
Execute transactional "recipes" for complex, multi-step AI workflows.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Run a project-local recipe
|
||||||
|
grokkit recipe run result-refactor
|
||||||
|
|
||||||
|
# Pass parameters to the recipe
|
||||||
|
grokkit recipe run result-refactor -p package_path=internal/git -p dry_run=false
|
||||||
|
|
||||||
|
# Run a specific recipe file
|
||||||
|
grokkit recipe run ./my-custom-recipe.md
|
||||||
|
```
|
||||||
|
|
||||||
|
### Recipe System
|
||||||
|
|
||||||
|
- **Local Recipes**: Stored in `.grokkit/recipes/*.md`.
|
||||||
|
- **Global Recipes**: Stored in `~/.local/share/grokkit/recipes/*.md`.
|
||||||
|
- Recipes are **markdown-based** with YAML frontmatter for parameters and configuration.
|
||||||
|
|
||||||
|
### Anatomy of a Recipe
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
---
|
||||||
|
name: result-refactor
|
||||||
|
description: Convert naked errors to Result[T] pattern
|
||||||
|
version: 1.0
|
||||||
|
|
||||||
|
parameters:
|
||||||
|
package_path:
|
||||||
|
type: string
|
||||||
|
default: internal
|
||||||
|
description: Package to refactor
|
||||||
|
|
||||||
|
project_languages:
|
||||||
|
- go
|
||||||
|
|
||||||
|
extensions:
|
||||||
|
go:
|
||||||
|
- .go
|
||||||
|
|
||||||
|
search_pattern: "if err != nil"
|
||||||
|
|
||||||
|
allowed_shell_commands:
|
||||||
|
- go test
|
||||||
|
- go vet
|
||||||
|
---
|
||||||
|
|
||||||
|
# Result[T] Refactoring
|
||||||
|
|
||||||
|
**Overview**
|
||||||
|
Converts traditional Go error handling to the modern Result[T] monadic style.
|
||||||
|
|
||||||
|
## Execution Steps
|
||||||
|
|
||||||
|
### Step 1: Discover files
|
||||||
|
**Objective:** Find files that need refactoring.
|
||||||
|
**Instructions:** Recursively scan `{{.package_path}}`...
|
||||||
|
**Expected output:** Clean list of full file paths.
|
||||||
|
|
||||||
|
### Step 2: Read-Only Shell: Explore project structure
|
||||||
|
**Objective:** Get additional context if needed.
|
||||||
|
**Instructions:** Use safe read-only commands...
|
||||||
|
|
||||||
|
### Step 3: Refactor each file
|
||||||
|
...
|
||||||
|
|
||||||
|
### Step 4: Apply or patch
|
||||||
|
...
|
||||||
|
```
|
||||||
|
|
||||||
|
### Key Features
|
||||||
|
|
||||||
|
* Parameters — override with --param key=value
|
||||||
|
* Read-only shell access — use steps titled "Read-Only Shell..." for safe ls, cat, tree, find, rg, jq, etc.
|
||||||
|
* User confirmation — you approve every shell command
|
||||||
|
* Dry-run safety — most recipes support dry_run=true by default
|
||||||
|
* Transactional — you see every step and can stop at any time
|
||||||
|
|
||||||
|
### Best Practices
|
||||||
|
|
||||||
|
* Keep recipes focused (one clear goal)
|
||||||
|
* Use "Read-Only Shell" steps when the LLM needs context
|
||||||
|
* Always include a good search_pattern for discovery
|
||||||
|
* Document expected output clearly in each step
|
||||||
|
|
||||||
48
docs/user-guide/review.md
Normal file
48
docs/user-guide/review.md
Normal file
@ -0,0 +1,48 @@
|
|||||||
|
# 🔍 Review Guide
|
||||||
|
|
||||||
|
The `review` command provides an AI-powered code review of your current repository or a specific directory. It analyzes your changes (git diff) and repository status to provide meaningful feedback.
|
||||||
|
|
||||||
|
### Key Features
|
||||||
|
|
||||||
|
- **Automated Code Review**: Get an instant review of your changes without waiting for a teammate.
|
||||||
|
- **Context-Aware**: Analyzes your staged and unstaged changes using `git diff` and `git status`.
|
||||||
|
- **Actionable Feedback**: Provides a concise summary and 3-5 specific, actionable improvements.
|
||||||
|
|
||||||
|
### Usage
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Review staged changes
|
||||||
|
git add feature.go
|
||||||
|
grokkit review
|
||||||
|
|
||||||
|
# Review all changes
|
||||||
|
grokkit review
|
||||||
|
|
||||||
|
# Get detailed review
|
||||||
|
grokkit review --debug # See API timing info
|
||||||
|
```
|
||||||
|
|
||||||
|
**Output includes:**
|
||||||
|
- Summary of changes
|
||||||
|
- 3-5 actionable improvements
|
||||||
|
- Potential bugs or issues
|
||||||
|
- Best practice suggestions
|
||||||
|
|
||||||
|
### Options
|
||||||
|
|
||||||
|
| Flag | Description |
|
||||||
|
|------|-------------|
|
||||||
|
| `--model`, `-m` | Override the default model (e.g., `grok-4`) |
|
||||||
|
|
||||||
|
### How it Works
|
||||||
|
|
||||||
|
1. **Change Analysis**: Grokkit runs `git status` and `git diff` to see what you've changed.
|
||||||
|
2. **Review Request**: It sends these changes to Grok with a specialized code review prompt.
|
||||||
|
3. **AI Evaluation**: Grok reviews the code for logic errors, style issues, and potential bugs.
|
||||||
|
4. **Summary and Tips**: You get a high-level summary and specific suggestions for improvement.
|
||||||
|
|
||||||
|
### Best Practices
|
||||||
|
|
||||||
|
- **Review small diffs**: For the most focused and useful feedback, run `review` frequently on smaller sets of changes.
|
||||||
|
- **Combine with Lint**: Run `grokkit lint` first to catch basic syntax and style issues, then use `review` for deeper logic analysis.
|
||||||
|
- **Model selection**: More complex changes may benefit from the deeper reasoning capabilities of `grok-4`.
|
||||||
31
docs/user-guide/safety.md
Normal file
31
docs/user-guide/safety.md
Normal file
@ -0,0 +1,31 @@
|
|||||||
|
# 🛡️ Safety & Change Management
|
||||||
|
|
||||||
|
Grokkit is designed to work seamlessly with Git. Rather than creating redundant `.bak` files, we lean on Git's powerful version control to manage changes and rollbacks.
|
||||||
|
|
||||||
|
## The Safety Workflow
|
||||||
|
|
||||||
|
1. **Preview**: Every command that modifies files (like `edit`, `lint`, `docs`) shows a diff-style preview first.
|
||||||
|
2. **Confirm**: You must explicitly confirm (`y/N`) before any changes are written to disk.
|
||||||
|
3. **Git Integration**: Use Git to manage the "pre-staged," "staged," and "committed" degrees of change.
|
||||||
|
|
||||||
|
## Managing Undesired Changes
|
||||||
|
|
||||||
|
If you've applied a change that you don't like, Git makes it easy to roll back:
|
||||||
|
|
||||||
|
- **Unstaged changes**: If you haven't `git add`-ed the changes yet:
|
||||||
|
```bash
|
||||||
|
git restore <file>
|
||||||
|
```
|
||||||
|
- **Staged changes**: If you've already staged the changes:
|
||||||
|
```bash
|
||||||
|
git restore --staged <file>
|
||||||
|
git restore <file>
|
||||||
|
```
|
||||||
|
- **Committed changes**: If you've already committed the changes:
|
||||||
|
```bash
|
||||||
|
git revert HEAD
|
||||||
|
# or to reset to a previous state:
|
||||||
|
git reset --hard HEAD~1
|
||||||
|
```
|
||||||
|
|
||||||
|
By using Git, you have a complete audit trail and multiple levels of undo, ensuring your codebase remains stable even when experimenting with AI-driven refactors.
|
||||||
50
docs/user-guide/scaffold.md
Normal file
50
docs/user-guide/scaffold.md
Normal file
@ -0,0 +1,50 @@
|
|||||||
|
# 🏗️ Scaffold Guide
|
||||||
|
|
||||||
|
The `scaffold` command allows you to quickly generate new files using AI that matches your project's existing coding style, naming conventions, and patterns.
|
||||||
|
|
||||||
|
### Features
|
||||||
|
|
||||||
|
- **Project context harvesting**: Analyzes siblings and directory structure for style matching.
|
||||||
|
- **Optional test generation**: Use `--with-tests` to generate a basic test file.
|
||||||
|
- **Safety checks**: Won't overwrite existing files without `--force`.
|
||||||
|
- **Language detection** and overrides (`--lang`).
|
||||||
|
|
||||||
|
### Usage
|
||||||
|
|
||||||
|
Scaffold a new file with Grok using project context for style matching.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Basic usage
|
||||||
|
grokkit scaffold internal/git/utils.go "git wrapper for listing tags"
|
||||||
|
|
||||||
|
# Scaffold with a basic test file
|
||||||
|
grokkit scaffold app.py "Flask route for health checks" --with-tests
|
||||||
|
|
||||||
|
# Preview without writing
|
||||||
|
grokkit scaffold main.go "simple CLI entrypoint" --dry-run
|
||||||
|
```
|
||||||
|
|
||||||
|
### Options
|
||||||
|
|
||||||
|
| Flag | Description |
|
||||||
|
|------|-------------|
|
||||||
|
| `--with-tests` | Also generate a basic test file (e.g., `utils_test.go`) |
|
||||||
|
| `--dry-run` | Preview the generated code without writing any files |
|
||||||
|
| `--yes`, `-y` | Skip the confirmation prompt and write files immediately |
|
||||||
|
| `--force` | Overwrite the destination file if it already exists |
|
||||||
|
| `--lang` | Manually specify the language (e.g., "Go", "Python", "TypeScript") |
|
||||||
|
| `--model`, `-m` | Override the default model (e.g., `grok-4`) |
|
||||||
|
|
||||||
|
### How it Works
|
||||||
|
|
||||||
|
1. **Context Harvesting**: Grokkit reads existing files in the same directory to understand your project's "vibe."
|
||||||
|
2. **Language Detection**: It automatically detects the language based on the file extension.
|
||||||
|
3. **AI Generation**: It sends the description and project context to Grok.
|
||||||
|
4. **Style Matching**: Grok is instructed to match the project's exact style.
|
||||||
|
5. **Confirmation**: You review the code and confirm before it's saved.
|
||||||
|
|
||||||
|
### Tips for Better Results
|
||||||
|
|
||||||
|
- **Be descriptive**: Instead of "a logger", try "a structured logger using slog that writes to a rotating file".
|
||||||
|
- **Use extensions**: Ensure your file path has the correct extension so Grokkit can detect the language.
|
||||||
|
- **Project layout**: Run `scaffold` in a directory that already contains some code for best style matching.
|
||||||
49
docs/user-guide/testgen.md
Normal file
49
docs/user-guide/testgen.md
Normal file
@ -0,0 +1,49 @@
|
|||||||
|
# 🧪 Testgen Guide
|
||||||
|
|
||||||
|
The `testgen` command generates high-quality unit tests for your existing code files using AI. It's designed to match your project's testing conventions and use the most modern practices for each language.
|
||||||
|
|
||||||
|
### Benefits
|
||||||
|
|
||||||
|
- **Go**: Table-driven `t.Parallel()` matching codebase.
|
||||||
|
- **Python**: Pytest with `@parametrize`.
|
||||||
|
- **C**: Check framework suites.
|
||||||
|
- **C++**: Google Test `EXPECT_*`.
|
||||||
|
- **Boosts coverage**; safe preview.
|
||||||
|
|
||||||
|
### Usage
|
||||||
|
|
||||||
|
Generate comprehensive unit tests for Go/Python/C/C++ files using AI.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
grokkit testgen internal/grok/client.go
|
||||||
|
grokkit testgen app.py --yes
|
||||||
|
grokkit testgen foo.c bar.cpp
|
||||||
|
```
|
||||||
|
|
||||||
|
### Safety Features
|
||||||
|
|
||||||
|
- **Lang detection** via `internal/linter`.
|
||||||
|
- **Unified diff preview**.
|
||||||
|
- **Y/N confirmation** (`--yes` to auto-confirm).
|
||||||
|
|
||||||
|
### Options
|
||||||
|
|
||||||
|
| Flag | Description |
|
||||||
|
|------|-------------|
|
||||||
|
| `--yes`, `-y` | Skip the confirmation prompt and write tests immediately |
|
||||||
|
| `--model`, `-m` | Override the default model (e.g., `grok-4`) |
|
||||||
|
|
||||||
|
### How it Works
|
||||||
|
|
||||||
|
1. **Language Detection**: Grokkit detects the language using its internal linter.
|
||||||
|
2. **Context Analysis**: It reads the source file and any existing test file.
|
||||||
|
3. **AI Generation**: It sends the source code to Grok with a language-specific system prompt.
|
||||||
|
4. **Style Matching**: Grok is instructed to use modern idioms and match the project's testing style.
|
||||||
|
5. **Interactive Diff**: If a test file already exists, it shows a diff of the proposed changes.
|
||||||
|
|
||||||
|
### Best Practices
|
||||||
|
|
||||||
|
- **Start with unit tests**: Test individual functions and methods.
|
||||||
|
- **Run tests immediately**: After `testgen` completes, run `make test` or your language-specific test runner to verify the generated tests.
|
||||||
|
- **Review for accuracy**: AI-generated tests are a great starting point, but always review them to ensure the logic and assertions are correct.
|
||||||
|
- **Coverage**: Use `make test-cover` (for Go) to see how much your new tests have improved your coverage.
|
||||||
21
docs/user-guide/version.md
Normal file
21
docs/user-guide/version.md
Normal file
@ -0,0 +1,21 @@
|
|||||||
|
# 🏷️ Version Guide
|
||||||
|
|
||||||
|
The `version` command prints the version, commit hash, and build date for the `grokkit` binary.
|
||||||
|
|
||||||
|
### Usage
|
||||||
|
|
||||||
|
```bash
|
||||||
|
grokkit version
|
||||||
|
```
|
||||||
|
|
||||||
|
### Output
|
||||||
|
|
||||||
|
```bash
|
||||||
|
grokkit version v0.1.0 (commit ab12cd3)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Why use Version?
|
||||||
|
|
||||||
|
- **Troubleshooting**: When reporting an issue, providing the version helps maintainers identify the state of the code you are using.
|
||||||
|
- **Verification**: Confirm that you have successfully installed the latest version or that your local build is up-to-date.
|
||||||
|
- **Consistency**: Ensure all team members are using the same version of the tool for reproducible results.
|
||||||
113
docs/user-guide/workflows.md
Normal file
113
docs/user-guide/workflows.md
Normal file
@ -0,0 +1,113 @@
|
|||||||
|
# 🔄 Grokkit Workflows
|
||||||
|
|
||||||
|
Learn how to integrate Grokkit into your development cycle effectively.
|
||||||
|
|
||||||
|
## Git Workflow Integration
|
||||||
|
|
||||||
|
The standard way to use Grokkit for your daily git tasks:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. Make changes
|
||||||
|
vim src/api.go
|
||||||
|
|
||||||
|
# 2. Review with AI
|
||||||
|
git add src/api.go
|
||||||
|
grokkit review
|
||||||
|
|
||||||
|
# 3. Fix issues, then commit
|
||||||
|
git add src/api.go
|
||||||
|
grokkit commit
|
||||||
|
|
||||||
|
# 4. Generate PR description
|
||||||
|
grokkit pr-describe
|
||||||
|
```
|
||||||
|
|
||||||
|
## Code Refactoring Workflow
|
||||||
|
|
||||||
|
Use Grokkit to plan and execute larger code changes:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. Chat to plan approach
|
||||||
|
grokkit chat
|
||||||
|
> "How should I refactor this authentication code to use middleware?"
|
||||||
|
|
||||||
|
# 2. Apply changes with edit
|
||||||
|
grokkit edit auth.go "implement middleware pattern as discussed"
|
||||||
|
|
||||||
|
# 3. Review changes
|
||||||
|
grokkit review
|
||||||
|
|
||||||
|
# 4. Commit
|
||||||
|
grokkit commit
|
||||||
|
```
|
||||||
|
|
||||||
|
## Debugging Workflow
|
||||||
|
|
||||||
|
Quickly identify and fix bugs using a combination of chat and editing:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. Describe issue in chat
|
||||||
|
grokkit chat --debug
|
||||||
|
> "I'm getting a nil pointer error in handler.go:42"
|
||||||
|
|
||||||
|
# 2. Apply suggested fixes
|
||||||
|
grokkit edit handler.go "add nil checks before dereferencing user object"
|
||||||
|
|
||||||
|
# 3. Verify and commit
|
||||||
|
grokkit review
|
||||||
|
grokkit commit
|
||||||
|
```
|
||||||
|
|
||||||
|
## Batch File Editing
|
||||||
|
|
||||||
|
Automate repetitive edits across many files:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Edit multiple files with consistent changes
|
||||||
|
for file in src/*.go; do
|
||||||
|
grokkit edit "$file" "add context parameter to all exported functions"
|
||||||
|
done
|
||||||
|
|
||||||
|
# Review all changes together
|
||||||
|
grokkit review
|
||||||
|
```
|
||||||
|
|
||||||
|
## Code Quality Workflow
|
||||||
|
|
||||||
|
Maintain high standards with AI-assisted linting and documentation:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. Check a file for linting issues
|
||||||
|
grokkit lint app.py --dry-run
|
||||||
|
|
||||||
|
# 2. Apply AI-suggested fixes with preview
|
||||||
|
grokkit lint app.py
|
||||||
|
|
||||||
|
# 3. Auto-fix multiple files
|
||||||
|
for file in src/*.js; do
|
||||||
|
grokkit lint "$file" --auto-fix
|
||||||
|
done
|
||||||
|
|
||||||
|
# 4. Review and commit
|
||||||
|
grokkit review
|
||||||
|
grokkit commit
|
||||||
|
```
|
||||||
|
|
||||||
|
## Documentation Generation Workflow
|
||||||
|
|
||||||
|
Generate comprehensive documentation for your project in seconds:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. Preview docs for a single file
|
||||||
|
grokkit docs internal/api/handler.go
|
||||||
|
|
||||||
|
# 2. Batch-document a package
|
||||||
|
grokkit docs cmd/*.go --auto-apply
|
||||||
|
|
||||||
|
# 3. Document across languages in one pass
|
||||||
|
grokkit docs lib/utils.py src/helpers.ts --auto-apply
|
||||||
|
|
||||||
|
# 4. Review and commit
|
||||||
|
grokkit review
|
||||||
|
grokkit commit
|
||||||
|
```
|
||||||
Loading…
Reference in New Issue
Block a user