Quick Start

Run your first Claw Code command in under a minute

This guide walks you through the most useful Claw Code commands. No installation step is needed beyond cloning the repo — everything runs directly as a Python module.

Claw Code requires Python 3.10 or later. See Installation for full setup instructions.

1. Clone the repo and enter it

   git clone https://github.com/instructkr/claw-code.git
   cd claw-code
   
2. Verify your Python version

   python3 --version
   

   Python 3.11.9
   

   Python 3.10 is the minimum supported version. The type annotation syntax used throughout src/ (for example, list[str] | None) will not parse on earlier releases.

3. Render the porting workspace summary

   The summary command builds a live manifest of the src/ tree and renders a Markdown report of the command and tool surface alongside session state.

   python3 -m src.main summary
   

   # Python Porting Workspace Summary
   
   Port root: `/path/to/claw-code/src`
   Total Python files: 84
   
   Top-level Python modules:
   - `main.py` (1 files) — CLI entrypoint
   - `commands.py` (1 files) — command backlog metadata
   - `tools.py` (1 files) — tool backlog metadata
   - `models.py` (1 files) — shared dataclasses
   - `query_engine.py` (1 files) — port orchestration summary layer
   - `port_manifest.py` (1 files) — workspace manifest generation
   - `runtime.py` (1 files) — Python port support module
   - `setup.py` (1 files) — Python port support module
   
   Command surface: 214 mirrored entries
   - add-dir [mirrored] — Command module mirrored from archived TypeScript path commands/add-dir/add-dir.tsx (from commands/add-dir/add-dir.tsx)
   - validation [mirrored] — Command module mirrored from archived TypeScript path commands/add-dir/validation.ts (from commands/add-dir/validation.ts)
   ...
   
   Tool surface: 154 mirrored entries
   - AgentTool [mirrored] — Tool module mirrored from archived TypeScript path tools/AgentTool/AgentTool.tsx (from tools/AgentTool/AgentTool.tsx)
   - UI [mirrored] — Tool module mirrored from archived TypeScript path tools/AgentTool/UI.tsx (from tools/AgentTool/UI.tsx)
   ...
   
   Session id: 3f7a2b1c...
   Conversation turns stored: 0
   Permission denials tracked: 0
   Usage totals: in=0 out=0
   Max turns: 8
   Max budget tokens: 2000
   Transcript flushed: False
   
4. List mirrored command entries

   The commands subcommand prints the mirrored command inventory. Use --limit to control how many entries are shown.

   python3 -m src.main commands --limit 5
   

   Command entries: 214
   
   - add-dir — commands/add-dir/add-dir.tsx
   - add-dir — commands/add-dir/index.ts
   - validation — commands/add-dir/validation.ts
   - advisor — commands/advisor.ts
   - agents — commands/agents/agents.tsx
   

   Pass --query to filter by name or source path, and --no-plugin-commands or --no-skill-commands to exclude plugin or skill entries.

5. Route a prompt

   The route command scores a natural-language prompt against both the command and tool inventories and returns the top matches ranked by relevance.

   python3 -m src.main route "read a file"
   

   tool	FileReadTool	2	tools/FileReadTool/FileReadTool.tsx
   command	read	1	commands/read/index.ts
   tool	fileRead	1	tools/FileReadTool/fileRead.ts
   

   Each line is tab-separated: kind, name, score, source_hint.

   Use --limit to increase or decrease the number of results (default: 5):

   python3 -m src.main route "write code" --limit 3
   

   tool	FileEditTool	2	tools/FileEditTool/FileEditTool.tsx
   command	write	1	commands/write/index.ts
   tool	fileWrite	1	tools/FileEditTool/fileWrite.ts
   
6. Bootstrap a session

   The bootstrap command runs a full runtime-style session report for a given prompt: it builds context, runs the setup report, routes the prompt, executes matched command and tool shims, streams events through the query engine, and persists the session to disk.

   python3 -m src.main bootstrap "write code"
   

   # Runtime Session
   
   Prompt: write code
   
   ## Context
   python_files=84  archive_available=False
   
   ## Setup
   - Python: 3.11.9 (CPython)
   - Platform: Linux-6.1.0-x86_64
   - Test command: python3 -m unittest discover -s tests -v
   
   ## Startup Steps
   - start top-level prefetch side effects
   - build workspace context
   - load mirrored command snapshot
   - load mirrored tool snapshot
   - prepare parity audit hooks
   - apply trust-gated deferred init
   
   ## Routed Matches
   - [tool] FileEditTool (2) — tools/FileEditTool/FileEditTool.tsx
   - [command] write (1) — commands/write/index.ts
   
   ## Turn Result
   Prompt: write code
   Matched commands: write
   Matched tools: FileEditTool
   Permission denials: 0
   
   Persisted session path: .port_sessions/3f7a2b1c.json
   

   The session JSON written to disk can be reloaded with python3 -m src.main load-session <session_id>.

Exploring further

Command	What it does
python3 -m src.main manifest	Print the raw workspace manifest
python3 -m src.main subsystems --limit 16	List top-level Python modules
python3 -m src.main tools --limit 10	List mirrored tool entries
python3 -m src.main parity-audit	Compare Python workspace against the TypeScript archive
python3 -m src.main setup-report	Show startup prefetch and deferred-init report
python3 -m src.main turn-loop "prompt"	Run a stateful multi-turn loop
python3 -m src.main command-graph	Show command graph segmentation
python3 -m src.main tool-pool	Show assembled tool pool
python3 -m src.main bootstrap-graph	Show bootstrap/runtime graph stages