CodeSavant

AI-powered autonomous coding agent CLI that brings Claude, GPT-4, Gemini, and other leading AI models directly to your terminal. Features autonomous workflows, a skill marketplace, self-improving brain, and design intelligence.

What's New in v4

• Autonomous /craft Cycle — End-to-end feature building: research, question, plan, build, verify — all orchestrated automatically
• Skill Marketplace — Browse, install, and publish reusable AI skills with version management and hash verification
• Self-Improving Brain — Cross-session learning that detects patterns, captures failures, and optimizes over time
• Design Intelligence — Frontend detection, design token vocabulary, and DesignBrief schemas for style-aware code generation
• Claude Code Parity — Structured bash output, CWD persistence, expanded error classification, rich debugging workflows

Features

• Multi-Provider Support — Anthropic Claude, OpenAI GPT-4, Groq, DeepSeek, Google Gemini, Ollama, and AWS Bedrock
• Interactive REPL — Rich terminal interface with streaming responses and real-time tool execution
• 20+ Built-in Tools — File operations, web search, code analysis, task management
• Autonomous Agent — Self-directed research, questioning, planning, and building via /craft
• Skill Marketplace — Browse, install, and publish community skills
• Self-Improving Brain — Pattern detection, failure capture, and cross-session learning
• Design Intelligence — Frontend detection, style vocabulary, and design token resolution
• Session Management — Save, resume, and checkpoint your conversations
• MCP Integration — Model Context Protocol support for extensibility
• Security First — Permission system with SSRF protection and command validation
• Context Management — Automatic token tracking and conversation compression

Installation

CodeSavant requires Bun runtime (v1.0.0+). The postinstall script will attempt to install Bun automatically if not found.

# Global installation (recommended)
npm install -g codesavant

# Or with bun
bun install -g codesavant

Quick Start

1. Launch

codesavant

On first run, you'll be prompted to configure your preferred AI provider and API key.

2. Start Chatting

> Read src/utils/parser.ts and suggest improvements

[Tool: Read] ✓ Complete
file: src/utils/parser.ts

│ Based on the code, here are my suggestions:
│ 1. Extract magic numbers into constants
│ 2. Add explicit return types
│ 3. Use more descriptive variable names...

Usage

Command-Line Interface

# Interactive REPL (default)
codesavant

# Single command execution
codesavant -p "explain this error"

# Pipe content as context
cat error.log | codesavant --pipe

# Resume a previous session
codesavant -r abc123

# Specify provider and model
codesavant --provider openai --model gpt-4o

# Permission modes
codesavant --plan       # Read-only tools
codesavant --yolo       # Auto-approve all
codesavant --strict     # Approve everything

CLI Options

| Option | Description | Example | |--------|-------------|---------| | -p, --print <prompt> | Execute prompt and exit | codesavant -p "fix bug" | | --pipe | Read prompt from stdin | cat file \| codesavant --pipe | | -r, --resume <id> | Resume previous session | codesavant -r abc123 | | --provider <name> | Set AI provider | codesavant --provider anthropic | | --model <name> | Set model | codesavant --model gpt-4o | | --plan | Read-only mode | codesavant --plan | | --yolo | Auto-approve all tools | codesavant --yolo | | --strict | Approve all tools manually | codesavant --strict | | --cwd <dir> | Set working directory | codesavant --cwd /project | | -o, --output-format | Output format (text/json/markdown) | codesavant -o json | | --version | Show version | codesavant --version |

REPL Commands

# Session
/session              # Show current session info
/session list         # List recent sessions
/resume [#|id]        # Resume a session
/checkpoint [name]    # Create checkpoint
/clear                # Clear conversation
/exit                 # Exit REPL

# Configuration
/config               # Show configuration
/status               # Show session status
/provider             # Display current provider
/model                # Display current model
/permissions [mode]   # Show/set permissions
/doctor               # Run health checks

# Context & Memory
/memory               # Show project memory
/context              # Show context usage
/history [count]      # Show recent messages
/cost                 # Show token usage
/compact              # Compress conversation

# Features
/help                 # Show all commands
/skills               # List available skills
/tasks                # Display task list
/mcp                  # Show MCP server status
/plan                 # Toggle plan mode
/rewind [args]        # Revert file changes

Supported AI Providers

Anthropic Claude

export ANTHROPIC_API_KEY="sk-ant-..."
codesavant --provider anthropic --model claude-sonnet-4-20250514

Models: claude-sonnet-4-20250514 (recommended), claude-opus-4-20250514, claude-haiku-4-20250414, claude-3-5-sonnet-20241022

OpenAI GPT-4

export OPENAI_API_KEY="sk-..."
codesavant --provider openai --model gpt-4o

Models: gpt-4o (recommended), gpt-4o-mini, gpt-4-turbo

Google Gemini

export GOOGLE_API_KEY="AIza..."
codesavant --provider gemini --model gemini-2.0-flash

Models: gemini-2.0-flash, gemini-1.5-pro, gemini-1.5-flash

Groq (Fast Inference)

export GROQ_API_KEY="gsk_..."
codesavant --provider groq --model llama-3.1-70b-versatile

DeepSeek

export DEEPSEEK_API_KEY="sk-..."
codesavant --provider deepseek --model deepseek-chat

Ollama (Local Models)

ollama serve && ollama pull llama3.2
codesavant --provider ollama --model llama3.2

AWS Bedrock

aws configure
codesavant --provider bedrock --model anthropic.claude-3-sonnet-20240229-v1:0

Autonomous /craft Workflows

The /craft command provides fully autonomous AI workflows that research, plan, build, and verify features end-to-end.

# Full autonomous cycle: research → question → plan → build → verify
/craft <feature description>

# Brainstorm and explore requirements
/craft ideate <feature description>

# Test-driven development
/craft proof <feature>

# Debug systematically
/craft diagnose <bug description>

# Create and execute plans
/craft blueprint <feature>
/craft build <plan>

# Quality checks
/craft inspect <claim>
/craft review
/craft ship

Skill Marketplace

Browse and install community-created skills, or publish your own.

/skills marketplace          # Browse available skills
/skills install <skill-name> # Install a skill
/skills publish <skill-path> # Publish your skill

Skills are verified with SHA-256 hash integrity checks and support semantic versioning.

Self-Improving Brain

CodeSavant learns across sessions:

• Pattern Detection — Identifies recurring coding patterns and preferences
• Failure Capture — Records what went wrong and how it was fixed
• Optimization — Detects opportunities to improve workflows
• Memory Resolution — Three-tier priority system (project > user > global)

Built-in Tools

File Operations

Read · Write · Edit · Glob · Grep

Code & Execution

Bash (structured stderr/stdout, CWD persistence, debugging workflows) · LSP · Notebook

Web & Search

WebSearch · WebFetch

Task Management

TaskCreate · TaskList · TaskUpdate

AI Features

Subagent (parallel agents) · Skill (custom workflows) · AskUser (interactive clarification)

Configuration

Settings File

CodeSavant uses .codesavant/settings.json:

{
  "providers": {
    "anthropic": { "apiKey": "sk-ant-..." }
  },
  "defaultProvider": "anthropic",
  "defaultModel": "claude-sonnet-4-20250514",
  "hooks": {
    "session_start": "echo 'Session started!'",
    "user_prompt_submit": "git status"
  },
  "permissions": { "mode": "default" }
}

Project Memory (SAVANT.md)

Create .codesavant/SAVANT.md for project context that AI reads automatically:

# Project: MyApp

## Architecture
- Next.js 14 app router
- PostgreSQL database

## Coding Standards
- Use TypeScript strict mode
- Write tests for all features

Custom Skills

Create custom skills in .codesavant/skills/:

---
name: deploy
description: Deploy to production
---

1. Run tests: `bun test`
2. Build: `bun run build`
3. Deploy: `vercel deploy --prod`

Security

Permission Modes

| Mode | Description | |------|-------------| | Default | Approve destructive operations interactively | | Plan (--plan) | Read-only, no file modifications | | YOLO (--yolo) | Auto-approve (use with caution) | | Strict (--strict) | Approve all tools manually |

Built-in Protections

• SSRF Protection — Blocks private IPs, localhost in WebFetch
• Path Validation — Prevents traversal attacks in file operations
• Command Safety — Array-based command spawning (no shell injection)
• Destructive Command Detection — Classifies and gates dangerous operations
• Tool Risk Assessment — High-risk tools require approval

Advanced Features

Hooks System

{
  "hooks": {
    "session_start": "git pull origin main",
    "user_prompt_submit": "git status",
    "pre_bash": "echo 'Running command...'",
    "pre_commit": "bun test"
  }
}

MCP Server Integration

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_..." }
    }
  }
}

Examples

Autonomous Feature Building

codesavant
> /craft user authentication with JWT

│ [Research] Spawning 4 parallel research agents...
│ [Questioning] 2 questions before building...
│ [Planning] Creating development roadmap...
│ [Building] Executing 3 plans with atomic commits...
│ [Verifying] Running quality checks...
│ ✓ Feature complete: 12 files, 8 commits, all tests passing

Pipe Mode

cat error.log | codesavant --pipe -p "analyze this error and suggest a fix"
git diff | codesavant --pipe -p "review these changes"

Session Management

codesavant
> /checkpoint oauth-implementation
> /exit

# Later, resume
codesavant -r

Troubleshooting

# Check provider authentication
codesavant
> /login

# Run diagnostics
> /doctor

License

MIT License — see LICENSE file for details.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Made with care by Vishal Aggarwal