ClawdCode

An AI-Powered CLI Coding Agent
Inspired by Claude Code — read, write, and execute code directly in your terminal.

Features • Installation • Quick Start • Architecture • Documentation

---

✨ Features

🤖 Intelligent Agent Agentic Loop: LLM + System Prompt + Context + Tools Streaming output with real-time response Thinking process with auto-collapse/expand Tool call display with compact dim-styled logs AbortController-based Ctrl+C interruption	🛠️ Built-in Tools (7) Read / Write / Edit — file operations with diff preview Glob / Grep — fast code search and pattern matching Bash — shell execution with permission control MCP — external tool integration via Model Context Protocol
🔒 Security & Permissions 4 permission modes: default / autoEdit / yolo / plan 7-stage execution pipeline with safety checks Inline permission prompt above input area Sensitive file detection (.env, credentials, etc.) Deny stops agent immediately — no continued thinking	🎨 Terminal UI Ink (React for CLI) — declarative interactive UI Markdown rendering with 140+ language syntax highlighting 5 built-in themes with auto dark/light detection Theme persistence across sessions Code block file paths and /copy clipboard support
🧩 Extensions Slash Commands — /help, /compact, /model, /theme, ... Custom Commands — Markdown files as commands, zero code Skills — pluggable agent capabilities via SKILL.md Hooks — 11 lifecycle events with pre/post shell scripts	📦 State & Context Zustand store with fine-grained subscriptions Token counting and auto-compaction Session persistence and resume (--continue) Command history with arrow key navigation MCP Registry for external tool servers

📥 Installation

# npm
npm install -g clawdcode
# pnpm
pnpm add -g clawdcode
# bun (recommended)
bun add -g clawdcode

🚀 Quick Start

1. Configure API Key

# Interactive setup
clawdcode --init
# Or set environment variableexport OPENAI_API_KEY=sk-your-api-key
# Or use other OpenAI-compatible providersexport OPENAI_BASE_URL=https://api.deepseek.com
export OPENAI_API_KEY=sk-your-deepseek-key

2. Start Coding

# Interactive mode
clawdcode
# With initial message
clawdcode "analyze this project structure"# With specific model
clawdcode --model gpt-4o
# Resume previous session
clawdcode --continue

3. Slash Commands

/help Show all commands
/clear Clear conversation
/compact Compress context (save tokens)
/model Switch model interactively
/theme Switch theme (dark/light/ocean/forest/sunset)
/status Show session info
/copy Copy code block to clipboard (/copy list)
/thinking Toggle thinking block expand/collapse
/mcp MCP server status
/hooks List active hooks
/skills List loaded skills

🏗️ Architecture

Coding Agent = LLM + System Prompt + Context + Tools

┌──────────────────────────────────────────────────────────┐
│ CLI Entry (yargs) │
│ ↓ │
│ Agent Loop ←──────────────────────────────┐ │
│ ├─ Build Context (messages + tools) │ │
│ ├─ Call LLM (streaming) │ │
│ ├─ Parse Response │ │
│ │ ├─ text → render to UI │ │
│ │ └─ tool_calls → Execution Pipeline │ │
│ │ ├─ 1. Discovery │ │
│ │ ├─ 2. Permission │ │
│ │ ├─ 3. Pre-Hooks │ │
│ │ ├─ 4. Confirmation (UI) │ │
│ │ ├─ 5. Execute │ │
│ │ ├─ 6. Post-Hooks │ │
│ │ └─ 7. Format │ │
│ └─ Inject Results ──────────────────────┘ │
│ │
│ Store (Zustand) ← → UI (Ink/React) ← → Theme Manager │
│ Context Manager ← → Token Counter ← → Compaction │
│ MCP Registry ← → External Tool Servers │
└──────────────────────────────────────────────────────────┘

📝 Custom Commands

Create project-specific commands in .clawdcode/commands/ (shareable via Git):

.clawdcode/commands/review.md

---description: Code review for current changes---
Review the current Git changes.
## Changes
!`git diff --stat HEAD~1`## Requirements1. Summarize what changed
2. Point out potential issues
3. Suggest improvements

.clawdcode/commands/test.md

---description: Run tests and analyze failuresargument-hint: [test file or pattern]allowed-tools:
- Bash(npm:*)
- Read---
Run tests: $ARGUMENTS
If any test fails, analyze the cause and suggest fixes.

Then use them:

/review # Code review
/test src/utils # Run specific tests

Dynamic Content Syntax

Syntax	Description	Example
$ARGUMENTS	All arguments	/cmd foo bar → foo bar
$1, $2	Positional args	/greet Alice → $1=Alice
!`cmd`	Bash embed	!`git branch`
@path	File reference	@package.json

⚙️ Configuration

ClawdCode supports multiple configuration methods (in priority order):

1. CLI arguments — --api-key, --base-url, --model
2. Environment variables — OPENAI_API_KEY, OPENAI_BASE_URL
3. Project config — ./.clawdcode/config.json
4. User config — ~/.clawdcode/config.json

Config File Example

{
"default": {
"apiKey": "sk-your-api-key",
"baseURL": "https://api.openai.com/v1",
"model": "gpt-4o"
},
"ui": {
"theme": "dark"
},
"permissions": {
"allow": ["Bash(npm:*)", "Bash(git:*)"],
"deny": ["Bash(rm -rf:*)"]
},
"mcpServers": {
"filesystem": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
}
}
}

Permission Modes

Mode	Read	Write	Execute	Description
default	✅	❓	❓	Ask for write/execute
autoEdit	✅	✅	❓	Auto-approve writes
yolo	✅	✅	✅	Full auto mode
plan	✅	❌	❌	Read-only analysis

clawdcode --permission yolo "fix all lint errors automatically"

Permission Rules

{
"permissions": {
"allow": [
"Read(**/*.ts)",
"Bash(npm:*)",
"Bash(git:*)"
],
"deny": [
"Bash(rm -rf:*)",
"Write(/etc/*)"
]
}
}

Rule format: ToolName(pattern)

• Exact: Bash(npm test)
• Prefix: Bash(npm:*) → matches npm install, npm test, etc.
• Glob: Read(**/*.ts) → matches all TypeScript files

Hooks

Add lifecycle hooks in .clawdcode/settings.json:

{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": ["echo 'About to run shell command: $TOOL_INPUT'"]
}
],
"PostToolUse": [
{
"matcher": "Write",
"hooks": ["npx prettier --write $FILE_PATH"]
}
],
"Notification": [
{
"matcher": "",
"hooks": ["terminal-notifier -message '$NOTIFICATION_MESSAGE'"]
}
]
}
}

11 hook events: PreToolUse, PostToolUse, Stop, UserPromptSubmit, Notification, etc.

💻 CLI Options

Usage: clawdcode [options] [message]
Options:
--api-key, -k OpenAI API key
--base-url, -b OpenAI API base URL
--model, -m Model to use (default: gpt-4o)
--permission, -p Permission mode (default/autoEdit/yolo/plan)
--theme, -t Color theme (dark/light/ocean/forest/sunset)
--continue, -c Resume previous session
--debug, -d Enable debug mode
--init Create default config file
--help, -h Show help
--version, -v Show version

🔧 Tech Stack

Technology	Role
TypeScript	Type safety, strict mode
Bun	Build & runtime
Ink	React for CLI — declarative terminal UI
Zustand	Lightweight state management
OpenAI SDK	Compatible with OpenAI / DeepSeek / local models
Zod	Runtime parameter validation
MCP	Model Context Protocol for external tools
lowlight	140+ language syntax highlighting

📖 Documentation

📚 Complete Tutorial — 17 Chapters — Build an AI CLI Coding Agent from scratch

Part	Chapters	Topics
Getting Started	01 - 03	Coding Agent overview, project setup, CLI entry
Core Architecture	04 - 07	Agent core, system prompt, tool system, execution pipeline
System Integration	08 - 12	Context management, UI system, MCP protocol, state management, command history
Extensions	13 - 17	Slash commands, interactive commands, streaming & themes, skills, hooks

💡 Examples

# Analyze project structure
clawdcode "analyze this project's architecture"# Fix TypeScript errors
clawdcode "fix all TypeScript type errors"# Code review (read-only mode)
clawdcode --permission plan "review the recent code changes"# Full auto mode
clawdcode --permission yolo "format all files with prettier"# Use DeepSeek
clawdcode --base-url https://api.deepseek.com --model deepseek-chat "refactor this function"

🛠 Development

# Clone
git clone https://github.com/kkkhs/ClawdCode.git
cd ClawdCode
# Install
bun install
# Dev
bun run dev
# Build
bun run build
# Type check
bun run typecheck

🤝 Contributing

Contributions welcome. Please submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feat/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feat/amazing-feature)
5. Open a Pull Request

📄 License

MIT © 2024-present

---

_{Built with ❤️ by kkkhs}