add missing parts
This commit is contained in:
Abdelrahman Abdallah
@@ -76,6 +76,330 @@ Built on the public porting workspace from [instructkr/claw-code](https://github
|
||||
- [ ] Some deeper runtime details from the npm source
|
||||
- [ ] Cost tracking and budget limits
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Architecture
|
||||
|
||||
```text
|
||||
claw-code/
|
||||
├── README.md
|
||||
├── pyproject.toml
|
||||
├── .gitignore
|
||||
├── images/
|
||||
│ └── logo.png
|
||||
├── src/ # Python implementation
|
||||
│ ├── main.py # CLI entry point & argument parsing
|
||||
│ ├── agent_runtime.py # Core agent loop (LocalCodingAgent)
|
||||
│ ├── agent_tools.py # Tool definitions & execution engine
|
||||
│ ├── agent_prompting.py # System prompt assembly
|
||||
│ ├── agent_context.py # Context building & CLAUDE.md discovery
|
||||
│ ├── agent_context_usage.py # Context usage estimation & reporting
|
||||
│ ├── agent_session.py # Session state management
|
||||
│ ├── agent_slash_commands.py # Local slash command processing
|
||||
│ ├── agent_types.py # Shared dataclasses & type definitions
|
||||
│ ├── openai_compat.py # OpenAI-compatible API client
|
||||
│ ├── session_store.py # Session serialization & persistence
|
||||
│ ├── permissions.py # Tool permission filtering
|
||||
│ ├── tools.py # Mirrored tool inventory
|
||||
│ ├── commands.py # Mirrored command inventory
|
||||
│ ├── ... # 75+ modules across 30+ packages
|
||||
│ ├── plugins/ # Plugin subsystem (WIP)
|
||||
│ ├── hooks/ # Hook system (WIP)
|
||||
│ ├── remote/ # Remote runtime modes (WIP)
|
||||
│ ├── voice/ # Voice mode (WIP)
|
||||
│ └── vim/ # VIM mode (WIP)
|
||||
└── tests/ # Unit tests
|
||||
├── test_agent_runtime.py
|
||||
├── test_agent_context.py
|
||||
├── test_agent_context_usage.py
|
||||
├── test_agent_prompting.py
|
||||
├── test_agent_slash_commands.py
|
||||
└── test_porting_workspace.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📦 Requirements
|
||||
|
||||
| Requirement | Details |
|
||||
|-------------|---------|
|
||||
| 🐍 Python | `3.10` or higher |
|
||||
| 🖥️ Model Server | `vLLM`, `Ollama`, or `LiteLLM Proxy`, with tool calling support |
|
||||
| 🧠 Model | [`Qwen/Qwen3-Coder-30B-A3B-Instruct`](https://huggingface.co/Qwen/Qwen3-Coder-30B-A3B-Instruct) (recommended) |
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### 1. Start vLLM with Qwen3-Coder
|
||||
|
||||
vLLM must be started with automatic tool choice enabled. Use the `qwen3_xml` parser for Qwen3-Coder tool calling:
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
Verify the server is running:
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:8000/v1/models
|
||||
```
|
||||
|
||||
> 📚 **References:** [vLLM Tool Calling Docs](https://docs.vllm.ai/en/v0.13.0/features/tool_calling/) · [OpenAI-Compatible Server](https://docs.vllm.ai/en/v0.13.0/serving/openai_compatible_server.html)
|
||||
|
||||
### Optional: Use Ollama Instead of vLLM
|
||||
|
||||
`claw-code-agent` can also work with Ollama because the runtime targets an OpenAI-compatible API. Use a model that supports tool calling well.
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
ollama serve
|
||||
ollama pull qwen3
|
||||
```
|
||||
|
||||
Then configure:
|
||||
|
||||
```bash
|
||||
export OPENAI_BASE_URL=http://127.0.0.1:11434/v1
|
||||
export OPENAI_API_KEY=ollama
|
||||
export OPENAI_MODEL=qwen3
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- prefer tool-capable models such as `qwen3`
|
||||
- plain chat-only models are not enough for full agent behavior
|
||||
- Ollama does not use the `vLLM` parser flags shown above
|
||||
|
||||
> 📚 **References:** [Ollama OpenAI Compatibility](https://docs.ollama.com/api/openai-compatibility) · [Ollama Tool Calling](https://docs.ollama.com/capabilities/tool-calling)
|
||||
|
||||
### Optional: Use LiteLLM Proxy
|
||||
|
||||
`claw-code-agent` can also work through LiteLLM Proxy because the runtime targets an OpenAI-compatible chat completions API. The routed model still needs to support tool calling for full agent behavior.
|
||||
|
||||
Quick start example:
|
||||
|
||||
```bash
|
||||
pip install 'litellm[proxy]'
|
||||
litellm --model ollama/qwen3
|
||||
```
|
||||
|
||||
LiteLLM Proxy runs on port `4000` by default. Then configure:
|
||||
|
||||
```bash
|
||||
export OPENAI_BASE_URL=http://127.0.0.1:4000
|
||||
export OPENAI_API_KEY=anything
|
||||
export OPENAI_MODEL=ollama/qwen3
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- LiteLLM Proxy gives you an OpenAI-style gateway in front of many providers
|
||||
- tool use still depends on the underlying routed model and provider behavior
|
||||
- if you configure a LiteLLM master key, use that instead of `anything`
|
||||
|
||||
> 📚 **References:** [LiteLLM Docs](https://docs.litellm.ai/) · [LiteLLM Proxy Quick Start](https://docs.litellm.ai/)
|
||||
|
||||
### 2. Configure Environment
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
### Use Another Model With vLLM
|
||||
|
||||
If you want to try another model, keep the same `vLLM` server setup and change the `--model` value when you launch `vLLM`.
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
python -m vllm.entrypoints.openai.api_server \
|
||||
--model your-model-name \
|
||||
--host 127.0.0.1 \
|
||||
--port 8000 \
|
||||
--enable-auto-tool-choice \
|
||||
--tool-call-parser your_parser
|
||||
```
|
||||
|
||||
Then update:
|
||||
|
||||
```bash
|
||||
export OPENAI_MODEL=your-model-name
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- the documented path in this repository is `vLLM`
|
||||
- the model must support tool calling well enough for agent use
|
||||
- some model families require a different `--tool-call-parser`
|
||||
- slash commands such as `/help`, `/context`, and `/tools` are local and do not require the model server
|
||||
|
||||
### 3. Run the Agent
|
||||
|
||||
```bash
|
||||
# Read-only question
|
||||
python3 -m src.main agent \
|
||||
"Read src/agent_runtime.py and summarize how the loop works." \
|
||||
--cwd .
|
||||
|
||||
# Write-enabled task
|
||||
python3 -m src.main agent \
|
||||
"Create TEST_QWEN_AGENT.md with one line: test ok" \
|
||||
--cwd . --allow-write
|
||||
|
||||
# Shell-enabled task
|
||||
python3 -m src.main agent \
|
||||
"Run pwd and ls src, then summarize the result." \
|
||||
--cwd . --allow-shell
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Usage
|
||||
|
||||
### Agent Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `agent <prompt>` | Run the agent with a prompt |
|
||||
| `agent-prompt` | Show the assembled system prompt |
|
||||
| `agent-context` | Show estimated context usage |
|
||||
| `agent-context-raw` | Show the raw context snapshot |
|
||||
| `agent-resume <id> <prompt>` | Resume a saved session |
|
||||
|
||||
### CLI Flags
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--cwd <path>` | Set the workspace directory |
|
||||
| `--model <name>` | Override the model name |
|
||||
| `--base-url <url>` | Override the API base URL |
|
||||
| `--allow-write` | Allow the agent to modify files |
|
||||
| `--allow-shell` | Allow the agent to execute shell commands |
|
||||
| `--unsafe` | Allow destructive shell operations |
|
||||
| `--show-transcript` | Print the full message transcript |
|
||||
| `--system-prompt <text>` | Set a custom system prompt |
|
||||
| `--append-system-prompt <text>` | Append to the system prompt |
|
||||
| `--add-dir <path>` | Add extra directories to context |
|
||||
|
||||
### Slash Commands
|
||||
|
||||
These are handled **locally** before the model loop:
|
||||
|
||||
| Command | Aliases | Description |
|
||||
|---------|---------|-------------|
|
||||
| `/help` | `/commands` | Show built-in slash commands |
|
||||
| `/context` | `/usage` | Show estimated session context usage |
|
||||
| `/context-raw` | `/env` | Show raw environment & context snapshot |
|
||||
| `/prompt` | `/system-prompt` | Render the effective system prompt |
|
||||
| `/permissions` | — | Show active tool permission mode |
|
||||
| `/model` | — | Show or update the active model |
|
||||
| `/tools` | — | List registered tools with permission status |
|
||||
| `/memory` | — | Show loaded CLAUDE.md memory bundle |
|
||||
| `/status` | `/session` | Show runtime/session status summary |
|
||||
| `/clear` | — | Clear ephemeral runtime state |
|
||||
|
||||
```bash
|
||||
python3 -m src.main agent "/help"
|
||||
python3 -m src.main agent "/context" --cwd .
|
||||
python3 -m src.main agent "/tools" --cwd .
|
||||
python3 -m src.main agent "/status" --cwd .
|
||||
```
|
||||
|
||||
### Utility Commands
|
||||
|
||||
```bash
|
||||
python3 -m src.main summary # Workspace summary
|
||||
python3 -m src.main manifest # Workspace manifest
|
||||
python3 -m src.main commands --limit 10 # Command inventory
|
||||
python3 -m src.main tools --limit 10 # Tool inventory
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
|
||||
## 🔧 Built-in Tools
|
||||
|
||||
The agent has access to 7 core tools:
|
||||
|
||||
| Tool | Description | Permission |
|
||||
|------|-------------|------------|
|
||||
| `list_dir` | List files and directories | 🟢 Always |
|
||||
| `read_file` | Read file contents (with line ranges) | 🟢 Always |
|
||||
| `write_file` | Write or create files | 🟡 `--allow-write` |
|
||||
| `edit_file` | Edit files via exact string matching | 🟡 `--allow-write` |
|
||||
| `glob_search` | Find files by glob pattern | 🟢 Always |
|
||||
| `grep_search` | Search file contents by regex | 🟢 Always |
|
||||
| `bash` | Execute shell commands | 🔴 `--allow-shell` |
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Session Persistence
|
||||
|
||||
Each `agent` run automatically saves a resumable session:
|
||||
|
||||
```text
|
||||
session_id=4f2c8c6f9c0e4d7c9c7b1b2a3d4e5f67
|
||||
session_path=.port_sessions/agent/4f2c8c6f...
|
||||
```
|
||||
|
||||
Resume a previous session:
|
||||
|
||||
```bash
|
||||
python3 -m src.main agent-resume \
|
||||
4f2c8c6f9c0e4d7c9c7b1b2a3d4e5f67 \
|
||||
"Continue the previous task and finish the missing parts."
|
||||
```
|
||||
|
||||
Inspect saved sessions:
|
||||
|
||||
```bash
|
||||
ls -lt .port_sessions/agent
|
||||
```
|
||||
|
||||
> **Note:** Run `agent-resume` from the same `claw-code/` directory where the session was created. A resumed session continues from the saved transcript, not from scratch.
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Testing
|
||||
|
||||
Run the full test suite:
|
||||
|
||||
```bash
|
||||
python3 -m unittest discover -s tests -v
|
||||
```
|
||||
|
||||
Smoke tests:
|
||||
|
||||
```bash
|
||||
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 .
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔐 Permission Model
|
||||
|
||||
Claw Code Agent uses a **tiered permission system** to keep the agent safe by default:
|
||||
|
||||
| Tier | Capability | Flag Required |
|
||||
|------|-----------|---------------|
|
||||
| **Read-only** | List, read, glob, grep | None (default) |
|
||||
| **Write** | + file creation and editing | `--allow-write` |
|
||||
| **Shell** | + shell command execution | `--allow-shell` |
|
||||
| **Unsafe** | + destructive shell operations | `--unsafe` |
|
||||
## 🔎 Detailed Parity Status Against npm `src`
|
||||
|
||||
This section tracks what is already implemented in Python and what is still missing compared with the upstream npm runtime in [`/src`](/data/fs201059/aa17626/claude_code_source/src).
|
||||
@@ -429,330 +753,6 @@ Mirrored inventory / scaffold areas that still need real implementation work:
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Architecture
|
||||
|
||||
```text
|
||||
claw-code/
|
||||
├── README.md
|
||||
├── pyproject.toml
|
||||
├── .gitignore
|
||||
├── images/
|
||||
│ └── logo.png
|
||||
├── src/ # Python implementation
|
||||
│ ├── main.py # CLI entry point & argument parsing
|
||||
│ ├── agent_runtime.py # Core agent loop (LocalCodingAgent)
|
||||
│ ├── agent_tools.py # Tool definitions & execution engine
|
||||
│ ├── agent_prompting.py # System prompt assembly
|
||||
│ ├── agent_context.py # Context building & CLAUDE.md discovery
|
||||
│ ├── agent_context_usage.py # Context usage estimation & reporting
|
||||
│ ├── agent_session.py # Session state management
|
||||
│ ├── agent_slash_commands.py # Local slash command processing
|
||||
│ ├── agent_types.py # Shared dataclasses & type definitions
|
||||
│ ├── openai_compat.py # OpenAI-compatible API client
|
||||
│ ├── session_store.py # Session serialization & persistence
|
||||
│ ├── permissions.py # Tool permission filtering
|
||||
│ ├── tools.py # Mirrored tool inventory
|
||||
│ ├── commands.py # Mirrored command inventory
|
||||
│ ├── ... # 75+ modules across 30+ packages
|
||||
│ ├── plugins/ # Plugin subsystem (WIP)
|
||||
│ ├── hooks/ # Hook system (WIP)
|
||||
│ ├── remote/ # Remote runtime modes (WIP)
|
||||
│ ├── voice/ # Voice mode (WIP)
|
||||
│ └── vim/ # VIM mode (WIP)
|
||||
└── tests/ # Unit tests
|
||||
├── test_agent_runtime.py
|
||||
├── test_agent_context.py
|
||||
├── test_agent_context_usage.py
|
||||
├── test_agent_prompting.py
|
||||
├── test_agent_slash_commands.py
|
||||
└── test_porting_workspace.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📦 Requirements
|
||||
|
||||
| Requirement | Details |
|
||||
|-------------|---------|
|
||||
| 🐍 Python | `3.10` or higher |
|
||||
| 🖥️ Model Server | `vLLM`, `Ollama`, or `LiteLLM Proxy`, with tool calling support |
|
||||
| 🧠 Model | [`Qwen/Qwen3-Coder-30B-A3B-Instruct`](https://huggingface.co/Qwen/Qwen3-Coder-30B-A3B-Instruct) (recommended) |
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### 1. Start vLLM with Qwen3-Coder
|
||||
|
||||
vLLM must be started with automatic tool choice enabled. Use the `qwen3_xml` parser for Qwen3-Coder tool calling:
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
Verify the server is running:
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:8000/v1/models
|
||||
```
|
||||
|
||||
> 📚 **References:** [vLLM Tool Calling Docs](https://docs.vllm.ai/en/v0.13.0/features/tool_calling/) · [OpenAI-Compatible Server](https://docs.vllm.ai/en/v0.13.0/serving/openai_compatible_server.html)
|
||||
|
||||
### Optional: Use Ollama Instead of vLLM
|
||||
|
||||
`claw-code-agent` can also work with Ollama because the runtime targets an OpenAI-compatible API. Use a model that supports tool calling well.
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
ollama serve
|
||||
ollama pull qwen3
|
||||
```
|
||||
|
||||
Then configure:
|
||||
|
||||
```bash
|
||||
export OPENAI_BASE_URL=http://127.0.0.1:11434/v1
|
||||
export OPENAI_API_KEY=ollama
|
||||
export OPENAI_MODEL=qwen3
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- prefer tool-capable models such as `qwen3`
|
||||
- plain chat-only models are not enough for full agent behavior
|
||||
- Ollama does not use the `vLLM` parser flags shown above
|
||||
|
||||
> 📚 **References:** [Ollama OpenAI Compatibility](https://docs.ollama.com/api/openai-compatibility) · [Ollama Tool Calling](https://docs.ollama.com/capabilities/tool-calling)
|
||||
|
||||
### Optional: Use LiteLLM Proxy
|
||||
|
||||
`claw-code-agent` can also work through LiteLLM Proxy because the runtime targets an OpenAI-compatible chat completions API. The routed model still needs to support tool calling for full agent behavior.
|
||||
|
||||
Quick start example:
|
||||
|
||||
```bash
|
||||
pip install 'litellm[proxy]'
|
||||
litellm --model ollama/qwen3
|
||||
```
|
||||
|
||||
LiteLLM Proxy runs on port `4000` by default. Then configure:
|
||||
|
||||
```bash
|
||||
export OPENAI_BASE_URL=http://127.0.0.1:4000
|
||||
export OPENAI_API_KEY=anything
|
||||
export OPENAI_MODEL=ollama/qwen3
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- LiteLLM Proxy gives you an OpenAI-style gateway in front of many providers
|
||||
- tool use still depends on the underlying routed model and provider behavior
|
||||
- if you configure a LiteLLM master key, use that instead of `anything`
|
||||
|
||||
> 📚 **References:** [LiteLLM Docs](https://docs.litellm.ai/) · [LiteLLM Proxy Quick Start](https://docs.litellm.ai/)
|
||||
|
||||
### 2. Configure Environment
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
### Use Another Model With vLLM
|
||||
|
||||
If you want to try another model, keep the same `vLLM` server setup and change the `--model` value when you launch `vLLM`.
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
python -m vllm.entrypoints.openai.api_server \
|
||||
--model your-model-name \
|
||||
--host 127.0.0.1 \
|
||||
--port 8000 \
|
||||
--enable-auto-tool-choice \
|
||||
--tool-call-parser your_parser
|
||||
```
|
||||
|
||||
Then update:
|
||||
|
||||
```bash
|
||||
export OPENAI_MODEL=your-model-name
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- the documented path in this repository is `vLLM`
|
||||
- the model must support tool calling well enough for agent use
|
||||
- some model families require a different `--tool-call-parser`
|
||||
- slash commands such as `/help`, `/context`, and `/tools` are local and do not require the model server
|
||||
|
||||
### 3. Run the Agent
|
||||
|
||||
```bash
|
||||
# Read-only question
|
||||
python3 -m src.main agent \
|
||||
"Read src/agent_runtime.py and summarize how the loop works." \
|
||||
--cwd .
|
||||
|
||||
# Write-enabled task
|
||||
python3 -m src.main agent \
|
||||
"Create TEST_QWEN_AGENT.md with one line: test ok" \
|
||||
--cwd . --allow-write
|
||||
|
||||
# Shell-enabled task
|
||||
python3 -m src.main agent \
|
||||
"Run pwd and ls src, then summarize the result." \
|
||||
--cwd . --allow-shell
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Usage
|
||||
|
||||
### Agent Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `agent <prompt>` | Run the agent with a prompt |
|
||||
| `agent-prompt` | Show the assembled system prompt |
|
||||
| `agent-context` | Show estimated context usage |
|
||||
| `agent-context-raw` | Show the raw context snapshot |
|
||||
| `agent-resume <id> <prompt>` | Resume a saved session |
|
||||
|
||||
### CLI Flags
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--cwd <path>` | Set the workspace directory |
|
||||
| `--model <name>` | Override the model name |
|
||||
| `--base-url <url>` | Override the API base URL |
|
||||
| `--allow-write` | Allow the agent to modify files |
|
||||
| `--allow-shell` | Allow the agent to execute shell commands |
|
||||
| `--unsafe` | Allow destructive shell operations |
|
||||
| `--show-transcript` | Print the full message transcript |
|
||||
| `--system-prompt <text>` | Set a custom system prompt |
|
||||
| `--append-system-prompt <text>` | Append to the system prompt |
|
||||
| `--add-dir <path>` | Add extra directories to context |
|
||||
|
||||
### Slash Commands
|
||||
|
||||
These are handled **locally** before the model loop:
|
||||
|
||||
| Command | Aliases | Description |
|
||||
|---------|---------|-------------|
|
||||
| `/help` | `/commands` | Show built-in slash commands |
|
||||
| `/context` | `/usage` | Show estimated session context usage |
|
||||
| `/context-raw` | `/env` | Show raw environment & context snapshot |
|
||||
| `/prompt` | `/system-prompt` | Render the effective system prompt |
|
||||
| `/permissions` | — | Show active tool permission mode |
|
||||
| `/model` | — | Show or update the active model |
|
||||
| `/tools` | — | List registered tools with permission status |
|
||||
| `/memory` | — | Show loaded CLAUDE.md memory bundle |
|
||||
| `/status` | `/session` | Show runtime/session status summary |
|
||||
| `/clear` | — | Clear ephemeral runtime state |
|
||||
|
||||
```bash
|
||||
python3 -m src.main agent "/help"
|
||||
python3 -m src.main agent "/context" --cwd .
|
||||
python3 -m src.main agent "/tools" --cwd .
|
||||
python3 -m src.main agent "/status" --cwd .
|
||||
```
|
||||
|
||||
### Utility Commands
|
||||
|
||||
```bash
|
||||
python3 -m src.main summary # Workspace summary
|
||||
python3 -m src.main manifest # Workspace manifest
|
||||
python3 -m src.main commands --limit 10 # Command inventory
|
||||
python3 -m src.main tools --limit 10 # Tool inventory
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
|
||||
## 🔧 Built-in Tools
|
||||
|
||||
The agent has access to 7 core tools:
|
||||
|
||||
| Tool | Description | Permission |
|
||||
|------|-------------|------------|
|
||||
| `list_dir` | List files and directories | 🟢 Always |
|
||||
| `read_file` | Read file contents (with line ranges) | 🟢 Always |
|
||||
| `write_file` | Write or create files | 🟡 `--allow-write` |
|
||||
| `edit_file` | Edit files via exact string matching | 🟡 `--allow-write` |
|
||||
| `glob_search` | Find files by glob pattern | 🟢 Always |
|
||||
| `grep_search` | Search file contents by regex | 🟢 Always |
|
||||
| `bash` | Execute shell commands | 🔴 `--allow-shell` |
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Session Persistence
|
||||
|
||||
Each `agent` run automatically saves a resumable session:
|
||||
|
||||
```text
|
||||
session_id=4f2c8c6f9c0e4d7c9c7b1b2a3d4e5f67
|
||||
session_path=.port_sessions/agent/4f2c8c6f...
|
||||
```
|
||||
|
||||
Resume a previous session:
|
||||
|
||||
```bash
|
||||
python3 -m src.main agent-resume \
|
||||
4f2c8c6f9c0e4d7c9c7b1b2a3d4e5f67 \
|
||||
"Continue the previous task and finish the missing parts."
|
||||
```
|
||||
|
||||
Inspect saved sessions:
|
||||
|
||||
```bash
|
||||
ls -lt .port_sessions/agent
|
||||
```
|
||||
|
||||
> **Note:** Run `agent-resume` from the same `claw-code/` directory where the session was created. A resumed session continues from the saved transcript, not from scratch.
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Testing
|
||||
|
||||
Run the full test suite:
|
||||
|
||||
```bash
|
||||
python3 -m unittest discover -s tests -v
|
||||
```
|
||||
|
||||
Smoke tests:
|
||||
|
||||
```bash
|
||||
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 .
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔐 Permission Model
|
||||
|
||||
Claw Code Agent uses a **tiered permission system** to keep the agent safe by default:
|
||||
|
||||
| Tier | Capability | Flag Required |
|
||||
|------|-----------|---------------|
|
||||
| **Read-only** | List, read, glob, grep | None (default) |
|
||||
| **Write** | + file creation and editing | `--allow-write` |
|
||||
| **Shell** | + shell command execution | `--allow-shell` |
|
||||
| **Unsafe** | + destructive shell operations | `--unsafe` |
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Disclaimer
|
||||
|
||||
- This repository is a **Python reimplementation** inspired by the Claude Code npm architecture.
|
||||
|
||||
Reference in New Issue
Block a user