Claw Code runs directly as a Python module from the repository. There is no pip install step — you clone the repo and invoke it with python3 -m src.main.
Prerequisites
Python 3.10 or later — required for the X | Y union syntax and match statements used across src/git — to clone the repository
Check your Python version with python3 --version. If you have multiple Python versions installed, make sure python3 resolves to 3.10 or higher, or invoke the correct binary explicitly (e.g., python3.11).
Install
Clone the repository
git clone https://github.com/instructkr/claw-code.git cd claw-code
(Optional) Create a virtual environment
Using a virtual environment keeps Claw Code’s dependencies isolated from your system Python. python3 -m venv .venv source .venv/bin/activate
Claw Code’s standard-library-only src/ core has no third-party dependencies, so a virtual environment is optional unless you add integrations later.
Verify installation
Print the workspace manifest to confirm the module loads correctly: python3 -m src.main manifest
You should see output similar to: 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
If you see an ImportError or ModuleNotFoundError, confirm you are running the command from the repository root (the directory that contains src/).
Run the test suite
Verify the workspace is functioning correctly by running the bundled unit tests: python3 -m unittest discover -s tests -v
A passing run ends with output like: ... ---------------------------------------------------------------------- Ran 42 tests in 0.143s OK
The test command is also stored in WorkspaceSetup.test_command and reported by python3 -m src.main setup-report.
Project structure The repository layout after cloning:
claw-code/ ├── src/ # Python porting workspace │ ├── __init__.py # package export surface │ ├── main.py # CLI entrypoint │ ├── port_manifest.py # workspace manifest generation │ ├── query_engine.py # port orchestration summary layer │ ├── commands.py # command backlog metadata │ ├── tools.py # tool backlog metadata │ ├── models.py # shared dataclasses │ ├── runtime.py # PortRuntime — routing and session bootstrap │ ├── setup.py # WorkspaceSetup and SetupReport │ ├── permissions.py # ToolPermissionContext deny-list │ ├── parity_audit.py # TypeScript archive comparison │ ├── session_store.py # session persistence │ ├── transcript.py # TranscriptStore │ ├── task.py # task-level planning structures │ ├── command_graph.py # command graph segmentation │ ├── tool_pool.py # assembled tool pool │ ├── bootstrap_graph.py # bootstrap/runtime graph stages │ ├── remote_runtime.py # remote-control/SSH/Teleport modes │ ├── direct_modes.py # direct-connect and deep-link modes │ └── reference_data/ │ ├── commands_snapshot.json # 200+ mirrored command entries │ ├── tools_snapshot.json # 150+ mirrored tool entries │ └── archive_surface_snapshot.json ├── tests/ # Python verification suite └── README.md
A Rust port is in progress on the dev/rust Next steps
Quick Start Run your first Claw Code command and explore the CLI.