Skip to main content

​
wit agent

The wit agent command provides an interactive AI-powered coding assistant that understands your codebase and can help with development tasks.

​
Overview

The wit agent is a conversational AI assistant that can:
  • Read and understand code files
  • Edit files with targeted changes
  • Run shell commands (npm, node, etc.)
  • Create branches and commits
  • Open pull requests
  • Explain code and suggest improvements

​
Usage

# Start interactive chat session
wit agent

# One-shot query
wit agent "explain the authentication flow"

# Explicit subcommands
wit agent chat              # Interactive session
wit agent ask <query>       # One-shot question
wit agent status            # Show agent configuration
wit agent help              # Show help

​
Interactive Mode

When you run wit agent without arguments, you enter an interactive chat session: 
$ wit agent

╭─────────────────────────────────────────╮
│          wit coding agent               │
╰─────────────────────────────────────────╯

Repository: /path/to/your/repo
Branch: main

Type your request, or use:
  help    - Show commands
  exit    - Exit the agent

>

​
Session Commands

Within an interactive session, you can use these commands:
CommandDescription
helpShow available commands
statusShow session status
historyShow conversation history
clearClear conversation history
exitExit the agent

​
One-Shot Mode

For quick questions, use one-shot mode: 
# Ask about code
wit agent "what does Repository.find() do?"

# Request changes
wit agent "add error handling to the API endpoints"

# Explain commits
wit agent "explain the last 5 commits"

# Using 'ask' subcommand
wit agent ask "how is authentication implemented?"

​
Capabilities

The agent has access to powerful tools for working with your codebase:

​
Code Understanding

  • Read any file in the repository
  • List directory contents
  • Semantic search across the codebase
  • Get git status, diff, and history

​
Code Modification

  • Write new files
  • Edit existing files with targeted changes
  • Stage files for commit
  • Create commits with messages

​
Git Operations

  • Get repository status
  • View diffs and changes
  • Switch branches
  • Create new branches
  • Resolve merge conflicts

​
Shell Execution

  • Run npm/yarn commands
  • Execute tests
  • Run build processes
  • Any shell command needed

​
Pull Requests

  • Generate PR descriptions
  • Open pull requests
  • Review code changes

​
Examples

​
Explain Code

$ wit agent "explain the authentication flow in this codebase"

The authentication system works as follows:

1. User credentials are validated in src/core/auth.ts
2. Sessions are managed using JWT tokens...

​
Add a Feature

$ wit agent
> add a test for the user service

I'll add a test for the user service. Let me first look at the existing 
test structure...

[Creates test file with appropriate tests]

Done! I've created src/__tests__/user-service.test.ts with tests for:
- User creation
- User retrieval
- User update

​
Fix a Bug

$ wit agent "fix the null pointer exception in the API handler"

I found the issue in src/api/handler.ts:42. The problem is that...

[Makes targeted edit to fix the issue]

​
Refactor Code

$ wit agent
> refactor the error handling in the api/ directory

I'll analyze the current error handling patterns and suggest improvements...

[Proposes and implements refactoring]

​
Configuration

​
Environment Variables

The agent requires an AI API key to function: 
# OpenAI (GPT models)
export OPENAI_API_KEY=sk-...

# Anthropic (Claude models)
export ANTHROPIC_API_KEY=sk-ant-...

# Optional: Override model
export WIT_AI_MODEL=openai/gpt-4o

​
Check Status

Verify your agent configuration: 
$ wit agent status

wit Agent Status

Available: Yes
Model: openai/gpt-4o
Provider: openai

Repository: /path/to/repo
Branch: main

​
Memory and Context

The agent maintains conversation history within a session using persistent memory. This means:
  • Context is preserved across messages in a session
  • You can refer back to previous discussions
  • The agent remembers what files it has seen
  • Use clear to start fresh

​
Thread Management

Each session creates a unique thread for tracking the conversation: 
> status

Session Status:
  Repository: /path/to/repo
  Branch: main
  Thread ID: abc123...
  Messages: 12
  Pending changes: 0

​
Best Practices

​
Be Specific

Instead of: 
wit agent "fix the bugs"
Try: 
wit agent "fix the null reference error in UserService.getById()"

​
Provide Context

wit agent "add validation to the user creation endpoint in src/api/users.ts"

​
Review Changes

The agent will show you what changes it makes. Always review before committing: 
> add input validation to the API

[Agent makes changes]

# Review the changes
wit diff

# If satisfied, commit
wit commit -m "Add input validation to API"

​
Troubleshooting

​
Agent Not Available

If you see “AI features require an API key”: 
# Set your API key
export OPENAI_API_KEY=sk-your-key-here

# Or use Anthropic
export ANTHROPIC_API_KEY=sk-ant-your-key-here

​
Model Errors

If you encounter model-specific errors: 
# Try a different model
export WIT_AI_MODEL=openai/gpt-4o-mini

​
Context Limits

For very large codebases:
  • Focus on specific directories or files
  • Use semantic search to find relevant code first
  • Break complex tasks into smaller steps