Commands Reference

Complete guide to all chu commands and their usage.

Setup Interactive Workflow Review Features Run ML Graph Config

`chu do` - Autonomous Execution

The flagship copilot command. Orchestrates 4 specialized agents to autonomously complete tasks with validation and auto-retry.

How It Works

chu do "add JWT authentication"

Agent Flow:

Analyzer - Understands codebase using dependency graph, reads relevant files
Planner - Creates minimal implementation plan, lists files to modify
File Validation - Extracts allowed files, blocks extras
Editor - Executes changes ONLY on planned files
Validator - Checks success criteria, triggers auto-retry if validation fails

Examples

chu do "fix authentication bug in login handler"
chu do "refactor error handling to use custom types"
chu do "add rate limiting to API endpoints" --supervised
chu do "optimize database queries" --interactive

Flags

--supervised - Require manual approval before implementation (critical tasks)
--interactive - Prompt when model selection is ambiguous
--dry-run - Show plan only, don’t execute
-v / --verbose - Show model selection and agent decisions
--max-attempts N - Maximum retry attempts (default: 3)

Benefits

Automatic model selection: queries performance history and picks the best model per agent
Auto-retry with feedback: switches to better models when validation fails
File validation: prevents creating unintended files or modifying wrong code
Success criteria: verifies task completion before finishing
Cost optimized: uses cheaper models for routing, better models for editing

See full agent architecture →

Setup Commands

`chu setup`

Initialize Chuchu configuration at ~/.chuchu.

chu setup

Creates:

~/.chuchu/profile.yaml – backend and model configuration
~/.chuchu/system_prompt.md – base system prompt
~/.chuchu/memories.jsonl – memory store for examples

`chu key [backend]`

Add or update API key for a backend provider.

chu key openrouter
chu key groq

`chu models update`

Update model catalog from available providers (OpenRouter, Groq, OpenAI, etc.).

chu models update

Interactive Modes

`chu chat`

Code-focused conversation mode. Routes queries to appropriate agents based on intent.

chu chat
chu chat "explain how authentication works"
echo "list go files" | chu chat

Agent routing:

query – read/understand code
edit – modify code
research – external information
test – run tests or commands
review – code review and critique

`chu tdd`

Incremental TDD mode. Generates tests first, then implementation.

chu tdd
chu tdd "slugify function with unicode support"

Workflow:

Clarify requirements
Generate tests
Generate implementation
Iterate and refine

Workflow Commands (Research → Plan → Implement)

`chu research [question]`

Document codebase and understand architecture.

chu research "How does authentication work?"
chu research "Explain the payment flow"

Creates a research document with findings and analysis.

`chu plan [task]`

Create detailed implementation plan with phases.

chu plan "Add user authentication"
chu plan "Implement webhook system"

Generates:

Problem statement
Current state analysis
Proposed changes with phases
Saved to ~/.chuchu/plans/

`chu implement <plan_file>`

Execute an approved plan phase-by-phase with verification.

chu implement ~/.chuchu/plans/2025-01-15-add-auth.md

Each phase:

Implemented
Verified (tests run)
User confirms before next phase

Code Quality

`chu review [target]`

NEW: Review code for bugs, security issues, and improvements against coding standards.

chu review main.go
chu review ./src
chu review .
chu review internal/agents/ --focus security

Options:

--focus / -f – Focus area (security, performance, error handling)

Reviews against standards:

Naming conventions (Clean Code, Code Complete)
Language-specific best practices
TDD principles
Error handling and edge cases

Output structure:

Summary: Overall assessment
Critical Issues: Must-fix bugs or security risks
Suggestions: Quality/performance improvements
Nitpicks: Style, naming preferences

Examples:

chu review main.go --focus "error handling"
chu review . --focus performance
chu review src/auth --focus security

Feature Generation

`chu feature [description]`

Generate tests + implementation with auto-detected language.

chu feature "slugify with unicode support and max length"

Supported languages:

Elixir (mix.exs)
Ruby (Gemfile)
Go (go.mod)
TypeScript (package.json)
Python (requirements.txt)
Rust (Cargo.toml)

Execution Mode

`chu run [task]`

Execute tasks with follow-up support. Two modes available:

1. AI-assisted mode (default when no args provided):

chu run                                    # Start interactive session
chu run "deploy to staging" --once         # Single AI execution

2. Direct REPL mode with command history:

chu run --raw                              # Interactive command execution
chu run "docker ps" --raw                  # Execute command and exit

AI-Assisted Mode

Provides intelligent command suggestions and execution:

Command history tracking
Output reference ($1, $2, $last)
Directory and environment management
Context preservation across commands

chu run
> deploy to staging
[AI executes fly deploy command]
> check if it's running
[AI executes status check]
> roll back if there are errors
[AI conditionally executes rollback]

Direct REPL Mode

Direct shell command execution with enhanced features:

chu run --raw
> ls -la
> cat $1                    # Reference previous command
> /history                  # Show command history
> /output 1                 # Show output of command 1
> /cd /tmp                  # Change directory
> /env MY_VAR=value         # Set environment variable
> /exit                     # Exit REPL

REPL Commands:

/exit, /quit - Exit run session
/help - Show available commands
/history - Show command history
/output <id> - Show output of previous command
/cd <dir> - Change working directory
/env [key[=value]] - Show/set environment variables

Command References:

$last - Reference the last command
$1, $2, … - Reference command by ID

Examples

# AI-assisted operational tasks
chu run "check postgres status"
chu run "make GET request to api.github.com/users/octocat"

# Direct command REPL for DevOps
chu run --raw
> docker ps
> docker logs $1            # Reference container from previous output
> /cd /var/log
> tail -f app.log

# Single-shot with piped input
echo "deploy to production" | chu run --once

Flags

--raw - Use direct command REPL mode (no AI)
--once - Force single-shot mode (backwards compatible)

Perfect for operational tasks, DevOps workflows, and command execution with history.

Machine Learning Commands

`chu ml list`

List available ML models.

chu ml list

Shows:

Model name
Description
Location
Status (trained/not trained)

`chu ml train <model>`

Train an ML model using Python.

chu ml train complexity
chu ml train intent

Available models:

complexity – Task complexity classifier (simple/complex/multistep)
intent – Intent classifier (query/editor/research/review)

Requirements:

Python 3.8+
Will create venv and install dependencies automatically

`chu ml test <model> [query]`

Test a trained model with a query.

chu ml test complexity "implement oauth"
chu ml test intent "explain this code"

Shows prediction and probabilities for all classes.

`chu ml eval <model> [-f file]`

Evaluate model performance on test dataset.

chu ml eval complexity
chu ml eval intent -f ml/intent/data/eval.csv

Shows:

Accuracy
Precision/Recall/F1 per class
Confusion matrix
Low-confidence predictions

`chu ml predict [model] <text>`

Make prediction using embedded Go model (no Python runtime).

chu ml predict "implement auth"               # uses complexity (default)
chu ml predict complexity "fix typo"          # explicit model
chu ml predict intent "explain this code"     # intent classification

Fast path:

1ms inference (vs 500ms LLM)
Zero API cost
Pure Go, no Python runtime

ML Configuration

Complexity Threshold

Controls when Guided Mode is automatically activated.

# View current threshold (default: 0.55)
chu config get defaults.ml_complex_threshold

# Set threshold (0.0-1.0)
chu config set defaults.ml_complex_threshold 0.6

Higher threshold = less sensitive (fewer Guided Mode triggers)

Intent Threshold

Controls when ML router is used instead of LLM.

# View current threshold (default: 0.7)
chu config get defaults.ml_intent_threshold

# Set threshold (0.0-1.0)
chu config set defaults.ml_intent_threshold 0.8

Higher threshold = more LLM fallbacks (more accurate but slower/expensive)

Dependency Graph Commands

`chu graph build`

Force rebuild dependency graph, ignoring cache.

chu graph build

Shows:

Number of nodes (files)
Number of edges (dependencies)
Build time

When to use:

After major refactoring
After adding/removing many files
If cache seems stale

`chu graph query <terms>`

Find relevant files for a query term using PageRank.

chu graph query "authentication"
chu graph query "database connection"
chu graph query "api routes"

Shows:

Matching files ranked by importance
PageRank scores
Why each file was selected

How it works:

Keyword matching in file paths
Neighbor expansion (imports/imported-by)
PageRank weighting
Top N selection

Graph Configuration

Max Files

Control how many files are added to context in chat mode.

# View current setting (default: 5)
chu config get defaults.graph_max_files

# Set max files (1-20)
chu config set defaults.graph_max_files 8

Recommendations:

Small projects (<50 files): 3-5
Medium projects (50-500 files): 5-8
Large projects (500+ files): 8-12

Debug Graph

export CHUCHU_DEBUG=1
chu chat "your query"  # Shows graph stats

Shows:

Nodes/edges count
Selected files
PageRank scores
Build time (cache hit/miss)

Command Comparison

Command	Purpose	When to Use
`chat`	Interactive conversation	Quick questions, exploratory work
`review`	Code review	Before commit, quality check, security audit
`tdd`	TDD workflow	New features requiring tests
`research`	Understand codebase	Architecture analysis, onboarding
`plan`	Create implementation plan	Large features, complex changes
`implement`	Execute plan	Structured feature implementation
`feature`	Quick feature generation	Small, focused features
`run`	Execute tasks	DevOps, HTTP requests, CLI commands

Environment Variables

`CHUCHU_DEBUG`

Enable debug output to stderr.

CHUCHU_DEBUG=1 chu chat

Shows:

Agent routing decisions
Iteration counts
Tool execution details

Configuration

All configuration lives in ~/.chuchu/:

~/.chuchu/
├── profile.yaml          # Backend and model settings
├── system_prompt.md      # Base system prompt
├── memories.jsonl        # Example memory store
└── plans/               # Saved implementation plans
    └── 2025-01-15-add-auth.md

Example profile.yaml

defaults:
  backend: groq
  model: fast

backends:
  groq:
    type: chat_completion
    base_url: https://api.groq.com/openai/v1
    default_model: llama-3.3-70b-versatile
    models:
      fast: llama-3.3-70b-versatile
      smart: llama-3.3-70b-specdec

Next Steps

See Research Mode for workflow details
See Plan Mode for plan structure

Commands Reference

Quick Navigation

chu do - Autonomous Execution

How It Works

Examples

Flags

Benefits

Setup Commands

chu setup

chu key [backend]

chu models update

Interactive Modes

chu chat

chu tdd

Workflow Commands (Research → Plan → Implement)

chu research [question]

chu plan [task]

chu implement <plan_file>

Code Quality

chu review [target]

Feature Generation

chu feature [description]

Execution Mode

chu run [task]

AI-Assisted Mode

Direct REPL Mode

Examples

Flags

Machine Learning Commands

chu ml list

chu ml train <model>

chu ml test <model> [query]

chu ml eval <model> [-f file]

chu ml predict [model] <text>

ML Configuration

Complexity Threshold

Intent Threshold

Dependency Graph Commands

chu graph build

chu graph query <terms>

Graph Configuration

Max Files

Debug Graph

Command Comparison

Environment Variables

CHUCHU_DEBUG

Configuration

Example profile.yaml

Next Steps

`chu do` - Autonomous Execution

`chu setup`

`chu key [backend]`

`chu models update`

`chu chat`

`chu tdd`

`chu research [question]`

`chu plan [task]`

`chu implement <plan_file>`

`chu review [target]`

`chu feature [description]`

`chu run [task]`

`chu ml list`

`chu ml train <model>`

`chu ml test <model> [query]`

`chu ml eval <model> [-f file]`

`chu ml predict [model] <text>`

`chu graph build`

`chu graph query <terms>`

`CHUCHU_DEBUG`