Quick Start

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.

Clone the repo and enter it

git clone https://github.com/instructkr/claw-code.git
cd claw-code

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.

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

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.

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

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

Get Started

Core Concepts

Guides

Exploring further

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

​Exploring further

Build docs developers (and LLMs) love

Exploring further