zk-data-agent/README.md

Claw Code Agent

Implementation of the Claude Code npm source architecture in Python.

This repository builds on the public porting workspace from instructkr/claw-code and extends it into a usable Python local-model agent. The active repository is HarnessLab/claw-code-agent. The goal is not to ship the npm source itself, but to reimplement the agent flow in Python: prompt assembly, context building, slash commands, tool calling, and local model execution.

Status

The Python runtime is working, but it is not full feature parity with the npm implementation yet.

Implemented now:

• Python CLI agent loop
• OpenAI-compatible local model backend
• Qwen3-Coder support through vLLM
• core tools: file read/write/edit, glob, grep, shell
• context building and /context-style usage reporting
• local slash commands such as /help, /context, /tools, /memory, /status
• unit tests for the Python runtime

Not complete yet:

• full plugin and MCP parity
• complete slash-command parity
• full interactive REPL/session persistence parity
• tokenizer-accurate context accounting

Repository Layout

claw-code/
├── README.md
├── .gitignore
├── src/
└── tests/

src/ contains the Python implementation.

tests/ contains the unit tests for the Python runtime.

Requirements

• Python 3.10+
• a local OpenAI-compatible model server
• recommended model: Qwen/Qwen3-Coder-30B-A3B-Instruct

Start vLLM With Qwen3-Coder

For Qwen3-Coder tool calling, vLLM must be started with automatic tool choice enabled. The official vLLM tool-calling docs describe --enable-auto-tool-choice and --tool-call-parser, and Qwen3-Coder should use the qwen3_xml parser:

• https://docs.vllm.ai/en/v0.13.0/features/tool_calling/
• https://docs.vllm.ai/en/v0.13.0/serving/openai_compatible_server.html

Example:

python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen3-Coder-30B-A3B-Instruct \
  --host 127.0.0.1 \
  --port 8000 \
  --enable-auto-tool-choice \
  --tool-call-parser qwen3_xml

Check that the server is up:

curl http://127.0.0.1:8000/v1/models

Environment Setup

From the claw-code/ directory:

export OPENAI_BASE_URL=http://127.0.0.1:8000/v1
export OPENAI_API_KEY=local-token
export OPENAI_MODEL=Qwen/Qwen3-Coder-30B-A3B-Instruct

How To Run

Show the agent system prompt:

python3 -m src.main agent-prompt --cwd .

Show estimated context usage:

python3 -m src.main agent-context --cwd .

Show the raw context snapshot:

python3 -m src.main agent-context-raw --cwd .

Run a read-only repo question:

python3 -m src.main agent \
  "Read src/agent_runtime.py and summarize how the loop works." \
  --cwd .

Run a write-enabled task:

python3 -m src.main agent \
  "Create TEST_QWEN_AGENT.md with one line: test ok" \
  --cwd . \
  --allow-write

Run a shell-enabled task:

python3 -m src.main agent \
  "Run pwd and ls src, then summarize the result." \
  --cwd . \
  --allow-shell

Show the full transcript:

python3 -m src.main agent \
  "Explain the current tool registry." \
  --cwd . \
  --show-transcript

Each real agent run now saves a resumable session and prints:

session_id=...
session_path=...

Resume a previous session:

python3 -m src.main agent-resume \
  <session-id> \
  "Continue the previous task and finish the missing implementation."

Resume A Previous Session

Each real agent run saves a resumable session automatically.

After a run finishes, the CLI prints:

session_id=...
session_path=...

You can continue the same task later by passing the saved session id:

python3 -m src.main agent-resume \
  <session-id> \
  "Continue the previous task and finish the missing parts."

Example:

python3 -m src.main agent-resume \
  4f2c8c6f9c0e4d7c9c7b1b2a3d4e5f67 \
  "Continue building the customer e-commerce project and complete the checkout flow."

Session files are stored under:

.port_sessions/agent/

You can inspect saved sessions with:

ls -lt .port_sessions/agent

Important notes:

• Run agent-resume from the same claw-code/ repository where the session was created.
• If you use --show-transcript, the session id is printed after the run output.
• A resumed session continues from the saved transcript, not from scratch.

Slash Command Examples

These are handled locally before the model loop:

python3 -m src.main agent "/help"
python3 -m src.main agent "/context" --cwd .
python3 -m src.main agent "/context-raw" --cwd .
python3 -m src.main agent "/tools" --cwd .
python3 -m src.main agent "/memory" --cwd .
python3 -m src.main agent "/status" --cwd .

How To Test

Run the full Python test suite:

python3 -m unittest discover -s tests -v

Optional smoke tests:

python3 -m src.main agent "/help"
python3 -m src.main agent-context --cwd .
python3 -m src.main agent \
  "Read src/agent_session.py and summarize the message flow." \
  --cwd .

Useful Commands

Workspace summary:

python3 -m src.main summary

Workspace manifest:

python3 -m src.main manifest

Mirrored command inventory:

python3 -m src.main commands --limit 10

Mirrored tool inventory:

python3 -m src.main tools --limit 10

Notes

• The Python agent is still CLI-based, but sessions are now persisted and can be resumed with agent-resume.
• --allow-write is required before the agent can modify files.
• --allow-shell is required before the agent can execute shell commands.
• --unsafe additionally allows destructive shell operations.

Disclaimer

• This repository is a Python implementation effort inspired by the Claude Code npm architecture.
• It does not ship the original npm source.
• It is not affiliated with or endorsed by Anthropic.