myclaw

A CLI coding agent scaffold (TypeScript + oclif).

See QUICK_START.md for a 5-minute setup guide.

Tech stack

• Node.js 20+
• TypeScript
• oclif
• execa (tool execution)
• cosmiconfig + dotenv (config)
• zod (schema)
• in-memory session store (v0.2.0 baseline)
• vitest (tests)

Quick start

npm install
npm run build
node ./bin/run.js init -f
# then fill credentials in ~/.myclaw/.env (or $MYCLAW_HOME/.env)

OPENAI_BASE_URL and .myclawrc.json baseURL both support OpenAI-compatible providers. Model priority: OPENAI_MODEL > .myclawrc.json model > gpt-4o-mini. Runtime priority: env vars > .myclawrc.json runtime > defaults.

Global Home Directory

• Default home: ~/.myclaw
• Override with env: MYCLAW_HOME=/custom/path
• Global env file: ~/.myclaw/.env
• Memory file: ~/.myclaw/memory.md
• Session logs: ~/.myclaw/sessions/<session-id>.jsonl
• Metrics logs: ~/.myclaw/metrics/<session-id>.jsonl

Example .myclawrc.json runtime block:

{
  "runtime": {
    "modelTimeoutMs": 45000,
    "modelRetryCount": 1,
    "maxSteps": 8,
    "contextWindowSize": 20
  }
}

Create your global env:

cp ~/.myclaw/.env.example ~/.myclaw/.env
# edit ~/.myclaw/.env

Commands

# Show resolved config
node ./bin/run.js config

# One-shot task
node ./bin/run.js run "implement hello world"

# Hide step logs and print only final answer
node ./bin/run.js run --quiet "implement hello world"

# Show raw model responses for each step (debug)
node ./bin/run.js run --verboseModel "implement hello world"

# Show per-event timing debug data
node ./bin/run.js run --debug "implement hello world"

# Disable interactive approval prompts (sensitive commands auto-denied)
node ./bin/run.js run --nonInteractive "implement hello world"

# Interactive chat mode
node ./bin/run.js chat

# Resume latest session for current workspace
node ./bin/run.js chat --resume latest

# Runtime diagnostics
node ./bin/run.js doctor
node ./bin/run.js doctor --json

# Init local config files
node ./bin/run.js init

Message Model

• Roles: system, user, assistant, tool
• Runtime: event-loop turn processing with tool execution feedback
• Context policy: system prompt + sliding window of recent 20 messages

Chat slash commands:

• /help
• /exit / /quit
• /clear
• /history [n]
• /config
• /sessions [n]
• /use <id|index|latest>

File mutation safety rules:

• Existing files must be read_file before write_file/apply_patch.
• New file creation is blocked by default. Use write_file with allowCreate=true only when explicitly needed.
• Destructive shell commands (for example rm, rmdir, unlink, del, git reset --hard, git clean) are treated as sensitive.
• Sensitive shell commands require interactive approval (WAITING FOR USER INPUT), otherwise they are denied.
• File discovery is supported with search_workspace before read_file.
• Multiple reads are allowed in one step.
• Only one mutation (write_file or apply_patch) is allowed per step.

Project structure

bin/                # CLI entrypoints (prod/dev)
src/commands/       # CLI commands
src/core/           # agent orchestration
src/providers/      # LLM provider abstraction
src/tools/          # executable tools
src/config/         # config loader + schema
test/               # tests

Known Limitations (v0.2.0)

• Tool-calling protocol is JSON-in-text parsing, not native function-calling.
• Session memory is in-process only (no persistent storage yet).
• No git-aware safety flow (branching, checkpoint, rollback) yet.
• Network/API retries and timeout policies are still basic.
• Permission model is coarse-grained; no per-tool policy profile yet.

TODO

• Add interactive chat mode with persistent SQLite session history.
• Add per-step command timeout/retry/backoff controls in config.
• Add git checkpoint + rollback command before mutation steps.
• Add path allowlist/denylist policy with per-tool enforcement.
• Add native tool/function-calling mode when provider supports it.
• Add E2E regression tests for multi-file debug scenarios.

Release Automation

GitHub Actions workflows are included:

• .github/workflows/ci.yml: build + test on push/PR
• .github/workflows/release.yml: publish npm + create GitHub Release on v* tags

Required repository secret:

• NPM_TOKEN: npm granular access token with publish permission for @sworddut/myclaw

Release command sequence:

npm version patch
git push origin main --follow-tags