codesavant 4.0.0 → 4.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +88 -456
  2. package/dist/cli.js +364 -297
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # CodeSavant
2
2
 
3
- > AI-powered autonomous coding agent CLI that brings Claude, GPT-4, and other leading AI models directly to your terminal. Features autonomous workflows, a skill marketplace, self-improving brain, and design intelligence.
3
+ > 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.
4
4
 
5
5
  [![NPM Version](https://img.shields.io/npm/v/codesavant.svg)](https://www.npmjs.com/package/codesavant)
6
6
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -8,98 +8,65 @@
8
8
 
9
9
  ---
10
10
 
11
- ## What's New in v4.0
11
+ ## What's New in v4
12
12
 
13
- - **Autonomous /craft Cycle** - End-to-end feature building: research, question, plan, build, verify -- all orchestrated automatically
14
- - **Skill Marketplace** - Browse, install, and publish reusable AI skills with version management and hash verification
15
- - **Self-Improving Brain** - Cross-session learning that detects patterns, captures failures, and optimizes over time
16
- - **Design Intelligence Foundation** - Frontend detection, design token vocabulary, and DesignBrief schemas for style-aware code generation
17
- - **360+ Test Files** - Comprehensive test coverage across unit, integration, e2e, performance, and security suites
13
+ - **Autonomous /craft Cycle** End-to-end feature building: research, question, plan, build, verify all orchestrated automatically
14
+ - **Skill Marketplace** Browse, install, and publish reusable AI skills with version management and hash verification
15
+ - **Self-Improving Brain** Cross-session learning that detects patterns, captures failures, and optimizes over time
16
+ - **Design Intelligence** Frontend detection, design token vocabulary, and DesignBrief schemas for style-aware code generation
17
+ - **Claude Code Parity** Structured bash output, CWD persistence, expanded error classification, rich debugging workflows
18
18
 
19
19
  ---
20
20
 
21
21
  ## Features
22
22
 
23
- - **Multi-Provider Support** - Works with Anthropic Claude, OpenAI GPT-4, Groq, DeepSeek, Google Gemini, Ollama, and AWS Bedrock
24
- - **Interactive REPL** - Rich terminal interface with streaming responses and real-time tool execution
25
- - **20+ Built-in Tools** - File operations, web search, code analysis, task management
26
- - **Autonomous Agent** - Self-directed research, questioning, planning, and building via /craft
27
- - **Skill Marketplace** - Browse, install, and publish community skills
28
- - **Self-Improving Brain** - Pattern detection, failure capture, and cross-session learning
29
- - **Design Intelligence** - Frontend detection, style vocabulary, and design token resolution
30
- - **Craft Skills** - AI-powered workflows for TDD, debugging, planning, and code review
31
- - **Session Management** - Save, resume, and checkpoint your conversations
32
- - **MCP Integration** - Model Context Protocol support for extensibility
33
- - **Security First** - Permission system with SSRF protection and command validation
34
- - **Context Management** - Automatic token tracking and conversation compression
23
+ - **Multi-Provider Support** Anthropic Claude, OpenAI GPT-4, Groq, DeepSeek, Google Gemini, Ollama, and AWS Bedrock
24
+ - **Interactive REPL** Rich terminal interface with streaming responses and real-time tool execution
25
+ - **20+ Built-in Tools** File operations, web search, code analysis, task management
26
+ - **Autonomous Agent** Self-directed research, questioning, planning, and building via /craft
27
+ - **Skill Marketplace** Browse, install, and publish community skills
28
+ - **Self-Improving Brain** Pattern detection, failure capture, and cross-session learning
29
+ - **Design Intelligence** Frontend detection, style vocabulary, and design token resolution
30
+ - **Session Management** Save, resume, and checkpoint your conversations
31
+ - **MCP Integration** Model Context Protocol support for extensibility
32
+ - **Security First** Permission system with SSRF protection and command validation
33
+ - **Context Management** Automatic token tracking and conversation compression
35
34
 
36
35
  ---
37
36
 
38
37
  ## Installation
39
38
 
40
- CodeSavant requires [Bun](https://bun.sh) runtime (v1.0.0+).
41
-
42
- ### Install Bun
39
+ CodeSavant requires [Bun](https://bun.sh) runtime (v1.0.0+). The postinstall script will attempt to install Bun automatically if not found.
43
40
 
44
41
  ```bash
45
- # macOS, Linux, WSL
46
- curl -fsSL https://bun.sh/install | bash
47
-
48
- # Or with npm
49
- npm install -g bun
50
- ```
51
-
52
- ### Install CodeSavant
42
+ # Global installation (recommended)
43
+ npm install -g codesavant
53
44
 
54
- ```bash
55
- # Global installation
45
+ # Or with bun
56
46
  bun install -g codesavant
57
-
58
- # Or with npm
59
- npm install -g codesavant
60
47
  ```
61
48
 
62
49
  ---
63
50
 
64
51
  ## Quick Start
65
52
 
66
- ### 1. Launch Interactive REPL
53
+ ### 1. Launch
67
54
 
68
55
  ```bash
69
56
  codesavant
70
57
  ```
71
58
 
72
- On first run, you'll be prompted to configure your preferred AI provider:
73
-
74
- ```
75
- Welcome to CodeSavant!
76
- No providers configured. Let's set one up.
77
-
78
- Which provider would you like to configure?
79
- 1. Anthropic (Claude)
80
- 2. OpenAI (GPT-4)
81
- 3. Groq (Fast inference)
82
- 4. Ollama (Local models)
83
- > 1
84
-
85
- Enter your Anthropic API key: sk-ant-...
86
- ✓ API key saved!
87
- ```
59
+ On first run, you'll be prompted to configure your preferred AI provider and API key.
88
60
 
89
61
  ### 2. Start Chatting
90
62
 
91
63
  ```
92
- > Hello! I need help refactoring my TypeScript code.
93
-
94
- │ I'd be happy to help you refactor your TypeScript code! Could you share
95
- │ the code you'd like to refactor, along with any specific goals you have?
96
-
97
64
  > Read src/utils/parser.ts and suggest improvements
98
65
 
99
66
  [Tool: Read] ✓ Complete
100
67
  file: src/utils/parser.ts
101
68
 
102
- │ Based on the code, here are my suggestions for refactoring:
69
+ │ Based on the code, here are my suggestions:
103
70
  │ 1. Extract magic numbers into constants
104
71
  │ 2. Add explicit return types
105
72
  │ 3. Use more descriptive variable names...
@@ -127,14 +94,10 @@ codesavant -r abc123
127
94
  # Specify provider and model
128
95
  codesavant --provider openai --model gpt-4o
129
96
 
130
- # Plan mode (read-only tools)
131
- codesavant --plan
132
-
133
- # YOLO mode (auto-approve all)
134
- codesavant --yolo
135
-
136
- # Strict mode (approve everything)
137
- codesavant --strict
97
+ # Permission modes
98
+ codesavant --plan # Read-only tools
99
+ codesavant --yolo # Auto-approve all
100
+ codesavant --strict # Approve everything
138
101
  ```
139
102
 
140
103
  ### CLI Options
@@ -152,50 +115,36 @@ codesavant --strict
152
115
  | `--cwd <dir>` | Set working directory | `codesavant --cwd /project` |
153
116
  | `-o, --output-format` | Output format (text/json/markdown) | `codesavant -o json` |
154
117
  | `--version` | Show version | `codesavant --version` |
155
- | `--help` | Show help | `codesavant --help` |
156
118
 
157
119
  ---
158
120
 
159
121
  ## REPL Commands
160
122
 
161
- Once in the interactive REPL, use these slash commands:
162
-
163
- ### Session Management
164
-
165
123
  ```bash
124
+ # Session
166
125
  /session # Show current session info
167
126
  /session list # List recent sessions
168
127
  /resume [#|id] # Resume a session
169
128
  /checkpoint [name] # Create checkpoint
170
129
  /clear # Clear conversation
171
130
  /exit # Exit REPL
172
- ```
173
-
174
- ### Configuration & Status
175
131
 
176
- ```bash
132
+ # Configuration
177
133
  /config # Show configuration
178
134
  /status # Show session status
179
135
  /provider # Display current provider
180
136
  /model # Display current model
181
137
  /permissions [mode] # Show/set permissions
182
- /login # Show auth status
183
138
  /doctor # Run health checks
184
- ```
185
-
186
- ### Context & Memory
187
139
 
188
- ```bash
140
+ # Context & Memory
189
141
  /memory # Show project memory
190
142
  /context # Show context usage
191
143
  /history [count] # Show recent messages
192
144
  /cost # Show token usage
193
145
  /compact # Compress conversation
194
- ```
195
146
 
196
- ### Features & Tools
197
-
198
- ```bash
147
+ # Features
199
148
  /help # Show all commands
200
149
  /skills # List available skills
201
150
  /tasks # Display task list
@@ -211,102 +160,55 @@ Once in the interactive REPL, use these slash commands:
211
160
  ### Anthropic Claude
212
161
 
213
162
  ```bash
214
- # Set API key
215
163
  export ANTHROPIC_API_KEY="sk-ant-..."
216
-
217
- # Use Claude
218
164
  codesavant --provider anthropic --model claude-sonnet-4-20250514
219
165
  ```
220
166
 
221
- **Models:**
222
- - `claude-sonnet-4-20250514` (recommended)
223
- - `claude-3-opus-20240229`
224
- - `claude-3-sonnet-20240229`
225
- - `claude-3-haiku-20240307`
167
+ **Models:** `claude-sonnet-4-20250514` (recommended), `claude-opus-4-20250514`, `claude-haiku-4-20250414`, `claude-3-5-sonnet-20241022`
226
168
 
227
169
  ### OpenAI GPT-4
228
170
 
229
171
  ```bash
230
- # Set API key
231
172
  export OPENAI_API_KEY="sk-..."
232
-
233
- # Use GPT-4
234
173
  codesavant --provider openai --model gpt-4o
235
174
  ```
236
175
 
237
- **Models:**
238
- - `gpt-4o` (recommended)
239
- - `gpt-4o-mini`
240
- - `gpt-4-turbo`
241
- - `gpt-4`
242
- - `gpt-3.5-turbo`
176
+ **Models:** `gpt-4o` (recommended), `gpt-4o-mini`, `gpt-4-turbo`
243
177
 
244
- ### Groq (Fast Inference)
178
+ ### Google Gemini
245
179
 
246
180
  ```bash
247
- # Set API key
248
- export GROQ_API_KEY="gsk_..."
249
-
250
- # Use Groq
251
- codesavant --provider groq --model llama-3.1-70b-versatile
181
+ export GOOGLE_API_KEY="AIza..."
182
+ codesavant --provider gemini --model gemini-2.0-flash
252
183
  ```
253
184
 
254
- **Models:**
255
- - `llama-3.1-70b-versatile`
256
- - `llama-3.2-90b-vision-preview`
257
- - `mixtral-8x7b-32768`
185
+ **Models:** `gemini-2.0-flash`, `gemini-1.5-pro`, `gemini-1.5-flash`
258
186
 
259
- ### Google Gemini
187
+ ### Groq (Fast Inference)
260
188
 
261
189
  ```bash
262
- # Set API key
263
- export GOOGLE_API_KEY="AIza..."
264
-
265
- # Use Gemini
266
- codesavant --provider gemini --model gemini-2.0-flash-exp
190
+ export GROQ_API_KEY="gsk_..."
191
+ codesavant --provider groq --model llama-3.1-70b-versatile
267
192
  ```
268
193
 
269
- **Models:**
270
- - `gemini-2.0-flash-exp`
271
- - `gemini-1.5-pro`
272
- - `gemini-1.5-flash`
273
-
274
194
  ### DeepSeek
275
195
 
276
196
  ```bash
277
- # Set API key
278
197
  export DEEPSEEK_API_KEY="sk-..."
279
-
280
- # Use DeepSeek
281
198
  codesavant --provider deepseek --model deepseek-chat
282
199
  ```
283
200
 
284
- **Models:**
285
- - `deepseek-chat`
286
- - `deepseek-coder`
287
-
288
201
  ### Ollama (Local Models)
289
202
 
290
203
  ```bash
291
- # Start Ollama server
292
- ollama serve
293
-
294
- # Pull a model
295
- ollama pull llama3.2
296
-
297
- # Use Ollama
204
+ ollama serve && ollama pull llama3.2
298
205
  codesavant --provider ollama --model llama3.2
299
206
  ```
300
207
 
301
- **Models:** Any Ollama model (llama3.2, codellama, mistral, etc.)
302
-
303
208
  ### AWS Bedrock
304
209
 
305
210
  ```bash
306
- # Configure AWS credentials
307
211
  aws configure
308
-
309
- # Use Bedrock
310
212
  codesavant --provider bedrock --model anthropic.claude-3-sonnet-20240229-v1:0
311
213
  ```
312
214
 
@@ -316,57 +218,29 @@ codesavant --provider bedrock --model anthropic.claude-3-sonnet-20240229-v1:0
316
218
 
317
219
  The `/craft` command provides fully autonomous AI workflows that research, plan, build, and verify features end-to-end.
318
220
 
319
- ### Process Skills (Use First)
320
-
321
221
  ```bash
222
+ # Full autonomous cycle: research → question → plan → build → verify
223
+ /craft <feature description>
224
+
322
225
  # Brainstorm and explore requirements
323
226
  /craft ideate <feature description>
324
227
 
325
- # Debug systematically
326
- /craft diagnose <bug description>
327
- ```
328
-
329
- ### Implementation Skills (During Work)
330
-
331
- ```bash
332
228
  # Test-driven development
333
229
  /craft proof <feature>
334
230
 
335
- # Create implementation plan
336
- /craft blueprint <feature>
231
+ # Debug systematically
232
+ /craft diagnose <bug description>
337
233
 
338
- # Execute plan step-by-step
234
+ # Create and execute plans
235
+ /craft blueprint <feature>
339
236
  /craft build <plan>
340
237
 
341
- # Parallel subagent execution
342
- /craft assembly-line <plan>
343
-
344
- # Create isolated git worktree
345
- /craft workspace <feature-name>
346
- ```
347
-
348
- ### Quality Skills (After Work)
349
-
350
- ```bash
351
- # Verify work with evidence
238
+ # Quality checks
352
239
  /craft inspect <claim>
353
-
354
- # Code review checklist
355
240
  /craft review
356
-
357
- # Final deployment checks
358
241
  /craft ship
359
242
  ```
360
243
 
361
- ### Full Autonomous Cycle
362
-
363
- ```bash
364
- # Fully autonomous: research → question → plan → build → verify
365
- /craft <feature description>
366
- ```
367
-
368
- The craft orchestrator spawns research agents in parallel, asks targeted questions, builds a development roadmap, executes plans with atomic commits, and verifies output quality -- all autonomously.
369
-
370
244
  ---
371
245
 
372
246
  ## Skill Marketplace
@@ -374,17 +248,12 @@ The craft orchestrator spawns research agents in parallel, asks targeted questio
374
248
  Browse and install community-created skills, or publish your own.
375
249
 
376
250
  ```bash
377
- # Browse available skills
378
- /skills marketplace
379
-
380
- # Install a skill
381
- /skills install <skill-name>
382
-
383
- # Publish your skill
384
- /skills publish <skill-path>
251
+ /skills marketplace # Browse available skills
252
+ /skills install <skill-name> # Install a skill
253
+ /skills publish <skill-path> # Publish your skill
385
254
  ```
386
255
 
387
- Skills are verified with SHA-256 hash integrity checks, support semantic versioning, and handle slug collisions gracefully.
256
+ Skills are verified with SHA-256 hash integrity checks and support semantic versioning.
388
257
 
389
258
  ---
390
259
 
@@ -392,70 +261,29 @@ Skills are verified with SHA-256 hash integrity checks, support semantic version
392
261
 
393
262
  CodeSavant learns across sessions:
394
263
 
395
- - **Pattern Detection** - Identifies recurring coding patterns and preferences
396
- - **Failure Capture** - Records what went wrong and how it was fixed
397
- - **Optimization** - Detects opportunities to improve workflows
398
- - **Memory Resolution** - Three-tier priority system (project > user > global)
399
-
400
- The brain operates transparently -- it writes insights after sessions and reads them before the next one, getting better over time without manual configuration.
401
-
402
- ---
403
-
404
- ## Design Intelligence
405
-
406
- CodeSavant automatically detects frontend work and applies design-aware context:
407
-
408
- - **Frontend Detection** - Identifies frontend tasks from file extensions (.tsx, .jsx, .css, .vue, .svelte), import patterns, and intent keywords
409
- - **Style Vocabulary** - 50+ design buzzwords (minimal, bold, cinematic, etc.) mapped to concrete design tokens
410
- - **Design Brief Schema** - Structured, validated design preferences with opinionated defaults
411
- - **Token Resolution** - Translates style buzzwords into actionable token hints (border-radius, spacing, contrast, etc.)
264
+ - **Pattern Detection** Identifies recurring coding patterns and preferences
265
+ - **Failure Capture** Records what went wrong and how it was fixed
266
+ - **Optimization** Detects opportunities to improve workflows
267
+ - **Memory Resolution** Three-tier priority system (project > user > global)
412
268
 
413
269
  ---
414
270
 
415
271
  ## Built-in Tools
416
272
 
417
- CodeSavant provides 20+ tools that AI can use to help you:
418
-
419
273
  ### File Operations
420
-
421
- | Tool | Description | Example Use |
422
- |------|-------------|-------------|
423
- | **Read** | Read file contents | "Read src/main.ts" |
424
- | **Write** | Create/overwrite files | "Create a new config.json" |
425
- | **Edit** | Modify existing files | "Update the port in server.ts to 3000" |
426
- | **Glob** | Find files by pattern | "Find all .tsx files" |
427
- | **Grep** | Search file contents | "Search for TODO comments" |
274
+ **Read** · **Write** · **Edit** · **Glob** · **Grep**
428
275
 
429
276
  ### Code & Execution
430
-
431
- | Tool | Description | Example Use |
432
- |------|-------------|-------------|
433
- | **Bash** | Execute shell commands | "Run the tests" |
434
- | **LSP** | Code analysis | "Get diagnostics for this file" |
435
- | **Notebook** | Jupyter notebook ops | "Read notebook cells" |
277
+ **Bash** (structured stderr/stdout, CWD persistence, debugging workflows) · **LSP** · **Notebook**
436
278
 
437
279
  ### Web & Search
438
-
439
- | Tool | Description | Example Use |
440
- |------|-------------|-------------|
441
- | **WebSearch** | Search the internet | "Search for React 18 docs" |
442
- | **WebFetch** | Fetch & analyze pages | "Fetch and summarize this article" |
280
+ **WebSearch** · **WebFetch**
443
281
 
444
282
  ### Task Management
445
-
446
- | Tool | Description | Example Use |
447
- |------|-------------|-------------|
448
- | **TaskCreate** | Create structured tasks | Used by workflows |
449
- | **TaskList** | List all tasks | "Show my tasks" |
450
- | **TaskUpdate** | Update task status | Automatic during work |
283
+ **TaskCreate** · **TaskList** · **TaskUpdate**
451
284
 
452
285
  ### AI Features
453
-
454
- | Tool | Description | Example Use |
455
- |------|-------------|-------------|
456
- | **Task (Subagent)** | Spawn parallel agents | For complex multi-step work |
457
- | **Skill** | Execute custom skills | Via /craft commands |
458
- | **AskUser** | Interactive questions | AI asks for clarification |
286
+ **Subagent** (parallel agents) · **Skill** (custom workflows) · **AskUser** (interactive clarification)
459
287
 
460
288
  ---
461
289
 
@@ -468,12 +296,7 @@ CodeSavant uses `.codesavant/settings.json`:
468
296
  ```json
469
297
  {
470
298
  "providers": {
471
- "anthropic": {
472
- "apiKey": "sk-ant-..."
473
- },
474
- "openai": {
475
- "apiKey": "sk-..."
476
- }
299
+ "anthropic": { "apiKey": "sk-ant-..." }
477
300
  },
478
301
  "defaultProvider": "anthropic",
479
302
  "defaultModel": "claude-sonnet-4-20250514",
@@ -481,15 +304,13 @@ CodeSavant uses `.codesavant/settings.json`:
481
304
  "session_start": "echo 'Session started!'",
482
305
  "user_prompt_submit": "git status"
483
306
  },
484
- "permissions": {
485
- "mode": "default"
486
- }
307
+ "permissions": { "mode": "default" }
487
308
  }
488
309
  ```
489
310
 
490
311
  ### Project Memory (SAVANT.md)
491
312
 
492
- Create `.codesavant/SAVANT.md` for project context:
313
+ Create `.codesavant/SAVANT.md` for project context that AI reads automatically:
493
314
 
494
315
  ```markdown
495
316
  # Project: MyApp
@@ -497,16 +318,12 @@ Create `.codesavant/SAVANT.md` for project context:
497
318
  ## Architecture
498
319
  - Next.js 14 app router
499
320
  - PostgreSQL database
500
- - tRPC API layer
501
321
 
502
322
  ## Coding Standards
503
323
  - Use TypeScript strict mode
504
- - Prefer functional components
505
324
  - Write tests for all features
506
325
  ```
507
326
 
508
- AI will read this automatically for project context.
509
-
510
327
  ### Custom Skills
511
328
 
512
329
  Create custom skills in `.codesavant/skills/`:
@@ -514,14 +331,9 @@ Create custom skills in `.codesavant/skills/`:
514
331
  ```markdown
515
332
  ---
516
333
  name: deploy
517
- category: implementation
518
334
  description: Deploy to production
519
335
  ---
520
336
 
521
- # Deploy Skill
522
-
523
- Follow these steps to deploy:
524
-
525
337
  1. Run tests: `bun test`
526
338
  2. Build: `bun run build`
527
339
  3. Deploy: `vercel deploy --prod`
@@ -531,22 +343,22 @@ Follow these steps to deploy:
531
343
 
532
344
  ## Security
533
345
 
534
- CodeSavant includes comprehensive security features:
535
-
536
346
  ### Permission Modes
537
347
 
538
- - **Default** - Approve destructive operations interactively
539
- - **Plan** (`--plan`) - Read-only, no file modifications
540
- - **YOLO** (`--yolo`) - Auto-approve (use with caution!)
541
- - **Strict** (`--strict`) - Approve all tools manually
348
+ | Mode | Description |
349
+ |------|-------------|
350
+ | **Default** | Approve destructive operations interactively |
351
+ | **Plan** (`--plan`) | Read-only, no file modifications |
352
+ | **YOLO** (`--yolo`) | Auto-approve (use with caution) |
353
+ | **Strict** (`--strict`) | Approve all tools manually |
542
354
 
543
355
  ### Built-in Protections
544
356
 
545
- - **SSRF Protection** - Blocks private IPs, localhost in WebFetch
546
- - **Path Validation** - Prevents traversal attacks in file operations
547
- - **Command Safety** - Array-based command spawning (no shell injection)
548
- - **Secrets Handling** - API keys from environment/config only
549
- - **Tool Risk Assessment** - High-risk tools require approval
357
+ - **SSRF Protection** Blocks private IPs, localhost in WebFetch
358
+ - **Path Validation** Prevents traversal attacks in file operations
359
+ - **Command Safety** Array-based command spawning (no shell injection)
360
+ - **Destructive Command Detection** Classifies and gates dangerous operations
361
+ - **Tool Risk Assessment** High-risk tools require approval
550
362
 
551
363
  ---
552
364
 
@@ -554,156 +366,64 @@ CodeSavant includes comprehensive security features:
554
366
 
555
367
  ### Hooks System
556
368
 
557
- Execute commands at key lifecycle events:
558
-
559
369
  ```json
560
370
  {
561
371
  "hooks": {
562
372
  "session_start": "git pull origin main",
563
373
  "user_prompt_submit": "git status",
564
- "session_end": "git stash"
374
+ "pre_bash": "echo 'Running command...'",
375
+ "pre_commit": "bun test"
565
376
  }
566
377
  }
567
378
  ```
568
379
 
569
380
  ### MCP Server Integration
570
381
 
571
- Connect external tools via Model Context Protocol:
572
-
573
382
  ```json
574
383
  {
575
384
  "mcpServers": {
576
385
  "github": {
577
386
  "command": "npx",
578
387
  "args": ["-y", "@modelcontextprotocol/server-github"],
579
- "env": {
580
- "GITHUB_TOKEN": "ghp_..."
581
- }
388
+ "env": { "GITHUB_TOKEN": "ghp_..." }
582
389
  }
583
390
  }
584
391
  }
585
392
  ```
586
393
 
587
- ### Background Tasks
588
-
589
- Run long operations in the background:
590
-
591
- ```bash
592
- > /bg npm run build
593
-
594
- │ Task started in background (ID: bg_abc123)
595
- │ You can continue working...
596
-
597
- > /tasks
598
-
599
- │ Active Tasks:
600
- │ ● bg_abc123: npm run build (Running, 45s)
601
- ```
602
-
603
- ### File Change Tracking
604
-
605
- Revert changes from previous operations:
606
-
607
- ```bash
608
- > /rewind
609
-
610
- │ Recent file changes:
611
- │ 1. src/config.ts (2 min ago)
612
- │ 2. src/auth.ts (5 min ago)
613
-
614
- │ Revert which file? (1-2, or 'all')
615
-
616
- > 1
617
-
618
- [Tool: Bash] ✓ Complete
619
- command: git restore src/config.ts
620
-
621
- │ ✓ Reverted src/config.ts
622
- ```
623
-
624
394
  ---
625
395
 
626
396
  ## Examples
627
397
 
628
- ### Example 1: Autonomous Feature Building
398
+ ### Autonomous Feature Building
629
399
 
630
400
  ```bash
631
401
  codesavant
632
-
633
402
  > /craft user authentication with JWT
634
403
 
635
- │ Starting autonomous craft cycle...
636
-
637
404
  │ [Research] Spawning 4 parallel research agents...
638
- Stack research complete
639
- │ ✓ Architecture research complete
640
- │ ✓ Security research complete
641
- │ ✓ Patterns research complete
642
-
643
- │ [Questioning] I have 2 questions before building:
644
- │ 1. Do you want refresh token rotation?
645
- │ 2. Session storage: Redis or in-memory?
646
-
647
- > Yes to refresh tokens, use Redis
648
-
405
+ [Questioning] 2 questions before building...
649
406
  │ [Planning] Creating development roadmap...
650
407
  │ [Building] Executing 3 plans with atomic commits...
651
408
  │ [Verifying] Running quality checks...
652
-
653
409
  │ ✓ Feature complete: 12 files, 8 commits, all tests passing
654
410
  ```
655
411
 
656
- ### Example 2: TDD Workflow
412
+ ### Pipe Mode
657
413
 
658
414
  ```bash
659
- codesavant
660
-
661
- > /craft proof login endpoint
662
-
663
- │ Starting TDD workflow. Writing failing tests first...
664
-
665
- [Tool: Write] ✓ Complete
666
- file: tests/api/login.test.ts
667
-
668
- │ ✗ 4 tests failing (expected). Now implementing minimal code to pass...
669
-
670
- [Tool: Write] ✓ Complete
671
- file: src/api/login.ts
672
-
673
- │ ✓ All 4 tests passing!
674
- ```
675
-
676
- ### Example 3: Pipe Mode
677
-
678
- ```bash
679
- # Analyze an error log
680
415
  cat error.log | codesavant --pipe -p "analyze this error and suggest a fix"
681
-
682
- # Review a diff
683
416
  git diff | codesavant --pipe -p "review these changes"
684
-
685
- # Explain code
686
- cat complex-algorithm.ts | codesavant --pipe -p "explain this algorithm step by step"
687
417
  ```
688
418
 
689
- ### Example 4: Session Management
419
+ ### Session Management
690
420
 
691
421
  ```bash
692
- # Start working on a feature
693
422
  codesavant
694
-
695
- > I need to add OAuth authentication
696
-
697
- │ Let's plan the OAuth implementation...
698
- │ [Long conversation with code changes]
699
-
700
423
  > /checkpoint oauth-implementation
701
-
702
- │ ✓ Checkpoint created: oauth-implementation
703
-
704
424
  > /exit
705
425
 
706
- # Later, resume the session
426
+ # Later, resume
707
427
  codesavant -r
708
428
  ```
709
429
 
@@ -711,108 +431,20 @@ codesavant -r
711
431
 
712
432
  ## Troubleshooting
713
433
 
714
- ### Provider Not Working
715
-
716
434
  ```bash
717
- # Check authentication
435
+ # Check provider authentication
718
436
  codesavant
719
437
  > /login
720
438
 
721
439
  # Run diagnostics
722
440
  > /doctor
723
-
724
- │ Running health checks...
725
- │ ✓ Provider: anthropic (authenticated)
726
- │ ✓ Storage: ~/.codesavant/ (writable)
727
- │ ✓ Working directory: /project (writable)
728
- │ ✓ All systems operational
729
- ```
730
-
731
- ### API Rate Limits
732
-
733
- ```bash
734
- > /cost
735
-
736
- │ Token Usage (This Session):
737
- │ - Input: 12,450 tokens
738
- │ - Output: 8,920 tokens
739
- │ - Total: 21,370 tokens
740
-
741
- │ Estimated Cost: $0.32
742
- ```
743
-
744
- ---
745
-
746
- ## Contributing
747
-
748
- We welcome contributions! CodeSavant is open source under the MIT license.
749
-
750
- ### Development Setup
751
-
752
- ```bash
753
- # Clone repository
754
- git clone https://github.com/vaggarwal039/codesavant.git
755
- cd codesavant
756
-
757
- # Install dependencies
758
- bun install
759
-
760
- # Run in development
761
- bun run src/cli.ts
762
-
763
- # Run tests
764
- bun test
765
-
766
- # Build for production
767
- bun run build
768
- ```
769
-
770
- ### Project Structure
771
-
772
- ```
773
- codesavant/
774
- ├── src/
775
- │ ├── cli.ts # CLI entry point
776
- │ ├── repl-ink.tsx # Interactive REPL
777
- │ ├── agent.ts # AI agent orchestration
778
- │ ├── providers/ # AI provider implementations
779
- │ ├── tools/ # Built-in tools
780
- │ ├── skills/ # Unified skill system
781
- │ ├── craft/ # Craft skill engine
782
- │ ├── craft-orchestrator/ # Autonomous build cycle
783
- │ ├── marketplace/ # Skill marketplace
784
- │ ├── brain/ # Self-improving brain
785
- │ ├── design/ # Design intelligence
786
- │ ├── components/ # UI components
787
- │ └── ...
788
- ├── tests/ # Test suite (360+ test files)
789
- ├── docs/ # Documentation
790
- └── package.json
791
441
  ```
792
442
 
793
443
  ---
794
444
 
795
445
  ## License
796
446
 
797
- MIT License - see [LICENSE](LICENSE) file for details.
798
-
799
- ---
800
-
801
- ## Acknowledgments
802
-
803
- Built with:
804
- - [Bun](https://bun.sh) - Fast JavaScript runtime
805
- - [Ink](https://github.com/vadimdemedes/ink) - React for CLIs
806
- - [Commander.js](https://github.com/tj/commander.js) - CLI framework
807
- - [Chalk](https://github.com/chalk/chalk) - Terminal styling
808
- - [Zod](https://zod.dev) - TypeScript schema validation
809
-
810
- Powered by:
811
- - [Anthropic Claude](https://anthropic.com)
812
- - [OpenAI GPT-4](https://openai.com)
813
- - [Google Gemini](https://deepmind.google/technologies/gemini/)
814
- - [Groq](https://groq.com)
815
- - [DeepSeek](https://deepseek.com)
447
+ MIT License see [LICENSE](LICENSE) file for details.
816
448
 
817
449
  ---
818
450