`bash
/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
`

$3

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

$3

`bash
/memory # Show project memory
/context # Show context usage
/history [count] # Show recent messages
/cost # Show token usage
/compact # Compress conversation
`

$3

`bash
/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

$3

`bash


Set API key

Models:
- claude-sonnet-4-20250514 (recommended)
- claude-3-opus-20240229
- claude-3-sonnet-20240229
- claude-3-haiku-20240307

$3

`bash


Set API key

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

$3

`bash


Set API key

Models:
- llama-3.1-70b-versatile
- llama-3.2-90b-vision-preview
- mixtral-8x7b-32768

$3

`bash


Set API key

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

$3

`bash


Set API key

Models:
- deepseek-chat
- deepseek-coder

$3

`bash


Start Ollama server

`bash


Configure AWS credentials

`bash


Brainstorm and explore requirements

Example:
`
> /craft ideate user authentication system

│ I'm using the ideate skill to brainstorm the authentication system.
│
│ Let's explore the requirements. What authentication method do you prefer?
│ 1. JWT tokens (stateless)
│ 2. Session-based (server-side state)
│ 3. OAuth 2.0 (third-party)
│
> 1

│ Great choice! Let's design a JWT-based auth system...
`

$3

`bash


Test-driven development

Example:
`
> /craft proof login endpoint

│ I'm using TDD workflow. Let me write failing tests first...
│
[Tool: Write] ✓ Complete
file: tests/auth/login.test.ts

│ Tests written. Running to verify they fail...
│
[Tool: Bash] ✓ Complete
command: bun test tests/auth/login.test.ts

│ ✗ 3 tests failing (expected). Now implementing minimal code to pass...
`

$3

`bash


Verify work with evidence

CodeSavant uses .codesavant/settings.json:

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

$3

Create .codesavant/SAVANT.md for project context:

`markdown


Project: MyApp

Architecture

Create custom skills in .codesavant/skills/:

`markdown
---
name: deploy
category: implementation
description: Deploy to production
---

Deploy Skill

Follow these steps to deploy:

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

---

🎨 Aurora Theme

CodeSavant features a modern "Aurora" color scheme:

- Electric Blue - Assistant messages, primary UI
- Aqua - User input, selections
- Emerald - Success states, completions
- Amber - Warnings, processing
- Crimson - Errors, failures
- Violet - Keywords, special states

Colors are optimized for terminal readability on both light and dark backgrounds.

---

💡 Examples

$3

`bash
codesavant

> Review the changes in src/auth.ts and suggest improvements

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

│ I've reviewed the authentication code. Here are my findings:
│
│ Security Issues:
│ 1. Line 23: Password stored in plaintext - should use bcrypt
│ 2. Line 45: JWT secret hardcoded - move to environment variable
│
│ Code Quality:
│ 1. Consider extracting validation logic into separate function
│ 2. Add error handling for database connection failures
│
│ Would you like me to fix these issues?

> Yes, fix the security issues

[Tool: Edit] ✓ Complete
file: src/auth.ts

│ I've updated the code to:
│ - Hash passwords with bcrypt
│ - Load JWT secret from environment variable
│ - Add proper error handling
│
│ Changes made to src/auth.ts (lines 23-50)
`

$3

`bash
codesavant

> /craft proof user registration endpoint

│ Starting TDD workflow. Writing failing tests first...

[Tool: Write] ✓ Complete
file: tests/api/register.test.ts

│ Test cases written:
│ 1. Should register new user with valid data
│ 2. Should reject duplicate email
│ 3. Should validate password strength
│ 4. Should return JWT token on success
│
│ Running tests...

[Tool: Bash] ✓ Complete
command: bun test tests/api/register.test.ts

│ ✗ All 4 tests failing (expected)
│
│ Now implementing minimal code to pass tests...

[Tool: Write] ✓ Complete
file: src/api/register.ts

[Tool: Bash] ✓ Complete
command: bun test tests/api/register.test.ts

│ ✓ All 4 tests passing!
│
│ Implementation complete. Ready to commit?

> Yes

[Tool: Bash] ✓ Complete
command: git add . && git commit -m "feat: add user registration endpoint"
`

$3

`bash
codesavant

> My app crashes with "Cannot read property 'name' of undefined"

│ Let's debug this systematically. Can you share the error stack trace
│ or the file where the error occurs?

> Read src/components/UserProfile.tsx

[Tool: Read] ✓ Complete
file: src/components/UserProfile.tsx

│ Found the issue at line 15:
│
│ `typescript
│ const userName = user.name; // user might be undefined
│ `
│
│ The problem is accessing user.name without checking if user exists first.
│
│ Root cause: The component renders before the user data is loaded.
│
│ Fix: Add a loading check:
│
│ `typescript
│ if (!user) return ;
│ const userName = user.name;
│ `
│
│ Should I apply this fix?

> Yes

[Tool: Edit] ✓ Complete
file: src/components/UserProfile.tsx
`

$3

`bash


Analyze an error log

`bash


Start working on a feature

> Continue with the OAuth implementation
`

---

🔐 Security

CodeSavant includes comprehensive security features:

$3

- 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

$3

- ✅ 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)
- ✅ Secrets Handling - API keys from environment/config only
- ✅ Tool Risk Assessment - High-risk tools require approval

$3

`bash


Use plan mode for exploratory analysis

`json
{
"hooks": {
"session_start": "git pull origin main",
"user_prompt_submit": "git status",
"session_end": "git stash"
}
}
`

$3

Connect external tools via Model Context Protocol:

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

$3

Run long operations in the background:

`bash
> /bg npm run build

│ Task started in background (ID: bg_abc123)
│ You can continue working...

> /tasks

│ Active Tasks:
│ ● bg_abc123: npm run build (Running, 45s)
`

$3

Revert changes from previous operations:

`bash
> /rewind

│ Recent file changes:
│ 1. src/config.ts (2 min ago)
│ 2. src/auth.ts (5 min ago)
│
│ Revert which file? (1-2, or 'all')

> 1

[Tool: Bash] ✓ Complete
command: git restore src/config.ts

│ ✓ Reverted src/config.ts
`

---

📊 Context Management

CodeSavant automatically manages context window:

`bash
> /context

│ Context Usage:
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 45,230 / 200,000 tokens (23%)
│
│ Breakdown:
│ - System: 2,450 tokens (5%)
│ - User: 18,920 tokens (42%)
│ - Assistant: 20,860 tokens (46%)
│ - Tools: 3,000 tokens (7%)
│
│ Status: ✓ Healthy
`

When approaching limits, use /compact to compress:

`bash
> /compact

│ Compressing conversation history...
│
│ Before: 45,230 tokens (23%)
│ After: 22,100 tokens (11%)
│
│ ✓ Compressed 50% of conversation
│ ✓ Key information preserved
`

---

🐛 Troubleshooting

$3

`bash


Check authentication

│ Running health checks...
│ ✓ Provider: anthropic (authenticated)
│ ✓ Storage: ~/.codesavant/ (writable)
│ ✓ Working directory: /project (writable)
│ ✓ All systems operational
`

$3

`bash


Check permissions

`bash


Check cost/usage

│ Token Usage (This Session):
│ - Input: 12,450 tokens
│ - Output: 8,920 tokens
│ - Total: 21,370 tokens
│
│ Estimated Cost: $0.32
`

---

🤝 Contributing

We welcome contributions! CodeSavant is open source under the MIT license.

$3

`bash


Clone repository

`
codesavant/
├── src/
│ ├── cli.ts # CLI entry point
│ ├── repl-ink.tsx # Interactive REPL
│ ├── agent.ts # AI agent orchestration
│ ├── providers/ # AI provider implementations
│ ├── tools/ # Built-in tools
│ ├── skills/ # Craft skills
│ ├── components/ # UI components
│ └── ...
├── tests/ # Test suite (4,500+ tests)
├── docs/ # Documentation
└── package.json
``

---

📄 License

MIT License - see LICENSE file for details.

---

🙏 Acknowledgments

Built with:
- Bun - Fast JavaScript runtime
- Ink - React for CLIs
- Commander.js - CLI framework
- Chalk - Terminal styling

Powered by:
- Anthropic Claude
- OpenAI GPT-4
- Google Gemini
- Groq
- DeepSeek

---

📞 Support

- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Email: vishal.a.aggarwal@pwc.com

---

🗺️ Roadmap

Coming soon:
- [ ] Web dashboard for session management
- [ ] VS Code extension
- [ ] Custom theme editor
- [ ] Team collaboration features
- [ ] Cloud session sync
- [ ] More AI providers (Cohere, Mistral, etc.)

---

Made with ❤️ by Vishal Aggarwal

Star ⭐ this repo if you find it useful!