🎅 SantaClaw

Your AI-Powered Terminal Engineer

Ask questions. Generate plans. Build features. Review every change. Stay in control.

SantaClaw is an approval-first AI coding assistant built for developers who want the power of autonomous agents without surrendering control of their codebase.

Unlike many AI coding tools that directly modify files, SantaClaw stages every proposed change and lets you review, approve, or reject modifications before they are applied.

Built with Bun, TypeScript, AI SDK, and a modular tool architecture.

Quick Start

Docker Deployment

Pull Image

docker pull sahilsingh94/santaclaw:latest

Run Container

docker run -it \
-e OPENROUTER_API_KEY=your_key \
-e TELEGRAM_BOT_TOKEN=your_token \
-e FIRECRAWL_API_KEY=your_key \
sahilsingh94/santaclaw:latest

Using an Environment File

Create a .env file:

OPENROUTER_API_KEY=your_key
TELEGRAM_BOT_TOKEN=your_token
FIRECRAWL_API_KEY=your_key

Run:

docker run -it --env-file .env sahilsingh94/santaclaw:latest

Docker Compose

services:
  santaclaw:
    image: sahilsingh94/santaclaw:latest
    env_file:
      - .env
    restart: unless-stopped

Start:

docker compose up -d

Build From Source

git clone https://github.com/<your-username>/SANTACLAW.git

cd SANTACLAW

docker build -t santaclaw .

Run:

docker run -it --env-file .env santaclaw

Required Environment Variables

Variable	Required	Description
OPENROUTER_API_KEY	Yes	LLM access
TELEGRAM_BOT_TOKEN	Optional	Telegram mode
FIRECRAWL_API_KEY	Optional	Web search and crawling

Troubleshooting

View logs:

docker logs <container-id>

List running containers:

docker ps

Verify environment variables:

docker exec -it <container-id> env

✨ Features

🤖 Autonomous Agent Mode

A fully autonomous coding agent capable of:

Understanding repository structure
Exploring project architecture
Searching and analyzing codebases
Creating new files
Modifying existing files
Refactoring code
Removing obsolete code
Generating implementation plans
Executing multi-step development workflows

Every modification is staged before application.

💡 Ask Mode

Ask questions about:

Your codebase
Programming concepts
System design
Architecture decisions
Performance bottlenecks
Debugging issues
Framework-specific problems
Best practices

SantaClaw analyzes project context before answering.

📋 Plan Mode

Generate implementation plans before writing code.

Ideal for:

New features
Refactors
Database migrations
API design
Microservice architecture
Project roadmaps
Learning unfamiliar codebases

📱 Telegram Mode

Use SantaClaw remotely through Telegram.

Access:

Ask Mode
Planning
Codebase discussions
Development workflows

from anywhere.

🔒 Approval-First Workflow

SantaClaw never silently changes your code.

Every action follows:

Analyze
   ↓
Understand
   ↓
Plan
   ↓
Generate Changes
   ↓
Stage Diff
   ↓
Review
   ↓
Approve / Reject
   ↓
Apply

You remain in control at every step.

🧠 Codebase Intelligence

SantaClaw builds contextual understanding before acting.

Capabilities include:

Repository exploration
Dependency discovery
Architecture analysis
File relationship mapping
Context gathering
Multi-file reasoning
Feature tracing

The goal is to understand before modifying.

🧰 Built-In Tool Ecosystem

Tool	Description
`read_file`	Read a file
`read_multiple_files`	Read multiple files simultaneously
`list_files`	Explore directories
`search_files`	Search codebases
`analyze_codebase`	Build repository understanding
`create_file`	Create new files
`modify_file`	Stage file modifications
`delete_file`	Stage file removals
`create_folder`	Create folders
`execute_shell`	Optional shell execution

The tool system is modular and extensible.

🚀 Why SantaClaw?

Most AI coding assistants optimize for automation.

SantaClaw optimizes for trust.

Capability	SantaClaw	Typical Agent
Repository Understanding	✅	✅
Autonomous Execution	✅	✅
Visible Planning	✅	⚠️
Staged Changes	✅	❌
Human Approval Gate	✅	❌
Terminal Native	✅	⚠️
Tool Transparency	✅	⚠️
Self-Hosted Friendly	✅	⚠️

SantaClaw treats developers as decision makers, not passengers.

🧠 Agent Architecture

SantaClaw follows a structured reasoning pipeline.

flowchart TD

A[User Prompt]
--> B[Intent Analysis]

B --> C[Repository Analysis]

C --> D[Context Collection]

D --> E[Planning Engine]

E --> F[Tool Execution]

F --> G[Diff Generation]

G --> H[Approval Gate]

H -->|Approve| I[Apply Changes]

H -->|Reject| J[Discard Changes]

Every step is explicit and observable.

⚙️ Internal Orchestration Pipeline

The agent operates through several coordinated phases.

flowchart LR

Prompt
--> Planner

Planner
--> Analyzer

Analyzer
--> ContextBuilder

ContextBuilder
--> Executor

Executor
--> DiffEngine

DiffEngine
--> ApprovalSystem

ApprovalSystem
--> User

Phase 1 — Intent Understanding

SantaClaw first determines:

What the user wants
Scope of requested work
Potential risks
Required context

Example:

"Add JWT authentication"

The agent identifies:

Authentication feature
Security-sensitive modification
Multi-file implementation

Phase 2 — Repository Analysis

The agent gathers context by:

Traversing directories
Reading configuration files
Identifying frameworks
Mapping dependencies

Example discoveries:

Express
Prisma
JWT already installed
User model exists

Phase 3 — Planning

The planner creates an implementation strategy.

Example:

1. Create JWT utility
2. Create auth middleware
3. Add login endpoint
4. Protect routes
5. Update documentation

Phase 4 — Execution

Tools execute the plan.

read_file()
search_files()
modify_file()
create_file()

Changes remain staged.

Phase 5 — Diff Generation

SantaClaw prepares a reviewable diff.

Example:

+ src/auth/jwt.ts
+ src/middleware/auth.ts
+ src/routes/auth.ts

- legacyAuth.ts

Nothing is applied yet.

Phase 6 — Approval Gate

The user reviews:

Approve?
[Y] Yes
[N] No

No approval = no modification.

🏗 System Architecture

flowchart TB

User

User --> TUI

TUI --> Router

Router --> AskMode
Router --> PlanMode
Router --> AgentMode

AgentMode --> Planner

Planner --> AIModel

Planner --> ToolLayer

ToolLayer --> FileSystem

ToolLayer --> SearchEngine

ToolLayer --> ShellExecution

AIModel --> DiffGenerator

DiffGenerator --> ApprovalGate

ApprovalGate --> User

🔄 Example Workflow

User Request

Add JWT authentication to my API

Repository Analysis

✓ Express detected

✓ Prisma detected

✓ Existing User model found

✓ No auth middleware present

Generated Plan

1. Install JWT dependency
2. Create token utility
3. Create auth middleware
4. Add login route
5. Protect endpoints

Generated Changes

+ src/auth/jwt.ts

+ src/middleware/auth.ts

+ src/routes/auth.ts

~ src/server.ts

Review Diff

──────────────────────────────
Review Generated Changes
──────────────────────────────

4 files modified

Approve?

[Y] Yes
[N] No

Apply

✓ Changes applied successfully

🔒 Safety Model

SantaClaw is designed around safe automation.

Security principles:

Human-in-the-Loop

Every modification requires approval.

Workspace Isolation

Operations are restricted to approved directories.

Explicit Tool Access

Dangerous tools can be disabled.

Diff Visibility

Every modification is reviewable.

Optional Shell Access

Shell execution is configurable.

📸 Screenshots

Main Menu

🎅 SantaClaw Workshop

1. Build
2. Ask
3. Plan
4. Telegram
5. Exit

Planning View

Generating implementation strategy...

✓ Context gathered
✓ Dependencies identified
✓ Plan generated

Diff Review

+ Added JWT utility
+ Added auth middleware
~ Updated server routes

Approve?

🧱 Technology Stack

Runtime

Bun

Language

TypeScript

AI Layer

AI SDK

Terminal UI

Clack
Chalk
Figlet

Messaging

Telegram Bot API

Architecture Principles

Approval First
Tool Driven
Context Aware
Terminal Native
Extensible
Transparent

🛣 Roadmap

Version 1

Version 2

Version 3

🚀 Installation

Clone Repository

git clone https://github.com/yourname/santaclaw.git

cd santaclaw

Install Dependencies

bun install

Start SantaClaw

bun run index.ts wakeup

🤝 Contributing

Contributions are welcome.

Ideas, bug reports, pull requests, feature proposals, and architectural discussions are encouraged.

Create a branch:

git checkout -b feature/amazing-feature

Build something cool and open a pull request.

📜 License

MIT License

Use freely. Modify freely. Build awesome things.

🎄 Built By SantaClaw

This documentation can be generated by SantaClaw itself.

The agent is capable of:

Exploring repositories
Understanding architecture
Identifying features
Producing technical documentation
Explaining implementation details

SantaClaw can document SantaClaw.

🎅 Ready to Build?

bun run index.ts wakeup

Ask. Plan. Build. Approve.

Your code. Your decisions. Your workshop.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
Tui		Tui
ai		ai
modes		modes
.dockerignore		.dockerignore
.gitignore		.gitignore
Dockerfile		Dockerfile
README.md		README.md
bun.lock		bun.lock
docker-compose.yml		docker-compose.yml
index.ts		index.ts
package-lock.json		package-lock.json
package.json		package.json
test-ask.md		test-ask.md
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation

🎅 SantaClaw

Your AI-Powered Terminal Engineer

Quick Start

Docker Deployment

Pull Image

Run Container

Using an Environment File

Docker Compose

Build From Source

Required Environment Variables

Troubleshooting

✨ Features

🤖 Autonomous Agent Mode

💡 Ask Mode

📋 Plan Mode

📱 Telegram Mode

🔒 Approval-First Workflow

🧠 Codebase Intelligence

🧰 Built-In Tool Ecosystem

🚀 Why SantaClaw?

🧠 Agent Architecture

⚙️ Internal Orchestration Pipeline

Phase 1 — Intent Understanding

Phase 2 — Repository Analysis

Phase 3 — Planning

Phase 4 — Execution

Phase 5 — Diff Generation

Phase 6 — Approval Gate

🏗 System Architecture

🔄 Example Workflow

User Request

Repository Analysis

Generated Plan

Generated Changes

Review Diff

Apply

🔒 Safety Model

Human-in-the-Loop

Workspace Isolation

Explicit Tool Access

Diff Visibility

Optional Shell Access

📸 Screenshots

Main Menu

Planning View

Diff Review

🧱 Technology Stack

Runtime

Language

AI Layer

Terminal UI

Messaging

Architecture Principles

🛣 Roadmap

Version 1

Version 2

Version 3

🚀 Installation

Clone Repository

Install Dependencies

Start SantaClaw

🤝 Contributing

📜 License

🎄 Built By SantaClaw

🎅 Ready to Build?

Ask. Plan. Build. Approve.

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages