diff --git a/README.md b/README.md
index 31afe63..09044a9 100644
--- a/README.md
+++ b/README.md
@@ -1,62 +1,133 @@
-# Claw Code Agent
-
- 
+
-Implementation of the Claude Code npm source architecture in Python.
+Claw Code Agent
-This repository builds on the public porting workspace from [instructkr/claw-code](https://github.com/instructkr/claw-code) and extends it into a usable Python local-model agent. The active repository is [HarnessLab/claw-code-agent](https://github.com/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.
+
+ A Python reimplementation of the Claude Code agent architecture โ local models, full control.
+
-## Status
+
+ 
+ 
+ 
+ 
+ 
+ 
+
-The Python runtime is working, but it is not full feature parity with the npm implementation yet.
+---
-Implemented now:
+## ๐ About
-- 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
+This repository reimplements the [Claude Code](https://docs.anthropic.com/en/docs/claude-code) npm agent architecture **entirely in Python**, designed to run with **local open-source models** via an OpenAI-compatible API server.
-Not complete yet:
+Built on the public porting workspace from [instructkr/claw-code](https://github.com/instructkr/claw-code), the active development lives at [HarnessLab/claw-code-agent](https://github.com/HarnessLab/claw-code-agent).
-- full plugin and MCP parity
-- complete slash-command parity
-- full interactive REPL/session persistence parity
-- tokenizer-accurate context accounting
+> **Goal:** Not to ship the original npm source, but to reimplement the full agent flow in Python โ prompt assembly, context building, slash commands, tool calling, session persistence, and local model execution.
-## Repository Layout
+---
+
+## โจ Key Features
+
+| Feature | Description |
+|---------|-------------|
+| ๐ค **Agent Loop** | Full agentic coding loop with tool calling and iterative reasoning |
+| ๐งฐ **Core Tools** | File read / write / edit, glob search, grep search, shell execution |
+| ๐ฌ **Slash Commands** | Local commands: `/help`, `/context`, `/tools`, `/memory`, `/status`, `/model`, and more |
+| ๐ง **Context Engine** | Automatic context building with CLAUDE.md discovery and usage reporting |
+| ๐ **Session Persistence** | Save and resume agent sessions across runs |
+| ๐ **Permission System** | Granular control: `--allow-write`, `--allow-shell`, `--unsafe` |
+| ๐๏ธ **OpenAI-Compatible** | Works with any OpenAI-compatible model server (vLLM, Ollama, etc.) |
+| ๐ **Qwen3-Coder** | First-class support for `Qwen3-Coder-30B-A3B-Instruct` via vLLM |
+
+---
+
+## ๐ Roadmap
+
+### Done
+
+- [x] Python CLI agent loop
+- [x] OpenAI-compatible local model backend
+- [x] Qwen3-Coder support through vLLM with `qwen3_xml` tool parser
+- [x] Core tools: `list_dir`, `read_file`, `write_file`, `edit_file`, `glob_search`, `grep_search`, `bash`
+- [x] Context building and `/context`-style usage reporting
+- [x] Slash commands: `/help`, `/context`, `/context-raw`, `/prompt`, `/permissions`, `/model`, `/tools`, `/memory`, `/status`, `/clear`
+- [x] Session persistence and `agent-resume` flow
+- [x] Permission system (read-only, write, shell, unsafe tiers)
+- [x] Unit tests for the Python runtime
+- [x] `pyproject.toml` packaging with `setuptools`
+
+### In Progress
+
+- [ ] Full plugin and MCP server parity
+- [ ] Complete slash-command parity with npm runtime
+- [ ] Full interactive REPL / session persistence parity
+- [ ] Tokenizer-accurate context accounting
+- [ ] Remote runtime modes (SSH, teleport, deep-link)
+- [ ] Voice and VIM modes
+- [ ] Hooks system
+- [ ] Cost tracking and budget limits
+
+---
+
+## ๐๏ธ Architecture
```text
claw-code/
โโโ README.md
+โโโ pyproject.toml
โโโ .gitignore
-โโโ src/
-โโโ tests/
+โโโ 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
```
-`src/` contains the Python implementation.
+---
-`tests/` contains the unit tests for the Python runtime.
+## ๐ฆ Requirements
-## Requirements
+| Requirement | Details |
+|-------------|---------|
+| ๐ Python | `3.10` or higher |
+| ๐ฅ๏ธ Model Server | Any OpenAI-compatible server (vLLM recommended) |
+| ๐ง Model | [`Qwen/Qwen3-Coder-30B-A3B-Instruct`](https://huggingface.co/Qwen/Qwen3-Coder-30B-A3B-Instruct) (recommended) |
-- Python 3.10+
-- a local OpenAI-compatible model server
-- recommended model: `Qwen/Qwen3-Coder-30B-A3B-Instruct`
+---
-## Start `vLLM` With Qwen3-Coder
+## ๐ Quick Start
-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:
+### 1. Start vLLM with Qwen3-Coder
-- 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:
+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 \
@@ -67,15 +138,15 @@ python -m vllm.entrypoints.openai.api_server \
--tool-call-parser qwen3_xml
```
-Check that the server is up:
+Verify the server is running:
```bash
curl http://127.0.0.1:8000/v1/models
```
-## Environment Setup
+> ๐ **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)
-From the `claw-code/` directory:
+### 2. Configure Environment
```bash
export OPENAI_BASE_URL=http://127.0.0.1:8000/v1
@@ -83,143 +154,141 @@ export OPENAI_API_KEY=local-token
export OPENAI_MODEL=Qwen/Qwen3-Coder-30B-A3B-Instruct
```
-## How To Run
-
-Show the agent system prompt:
-
-```bash
-python3 -m src.main agent-prompt --cwd .
-```
-
-Show estimated context usage:
-
-```bash
-python3 -m src.main agent-context --cwd .
-```
-
-Show the raw context snapshot:
-
-```bash
-python3 -m src.main agent-context-raw --cwd .
-```
-
-Run a read-only repo question:
+### 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 .
-```
-Run a write-enabled task:
-
-```bash
+# Write-enabled task
python3 -m src.main agent \
"Create TEST_QWEN_AGENT.md with one line: test ok" \
- --cwd . \
- --allow-write
-```
+ --cwd . --allow-write
-Run a shell-enabled task:
-
-```bash
+# Shell-enabled task
python3 -m src.main agent \
"Run pwd and ls src, then summarize the result." \
- --cwd . \
- --allow-shell
+ --cwd . --allow-shell
```
-Show the full transcript:
+---
+
+## ๐ ๏ธ Usage
+
+### Agent Commands
+
+| Command | Description |
+|---------|-------------|
+| `agent ` | 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 ` | Resume a saved session |
+
+### CLI Flags
+
+| Flag | Description |
+|------|-------------|
+| `--cwd ` | Set the workspace directory |
+| `--model ` | Override the model name |
+| `--base-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 ` | Set a custom system prompt |
+| `--append-system-prompt ` | Append to the system prompt |
+| `--add-dir ` | 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 \
- "Explain the current tool registry." \
- --cwd . \
- --show-transcript
+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 .
```
-Each real `agent` run now saves a resumable session and prints:
+### 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=...
-session_path=...
+session_id=4f2c8c6f9c0e4d7c9c7b1b2a3d4e5f67
+session_path=.port_sessions/agent/4f2c8c6f...
```
Resume a previous session:
```bash
python3 -m src.main agent-resume \
- \
- "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:
-
-```text
-session_id=...
-session_path=...
-```
-
-You can continue the same task later by passing the saved session id:
-
-```bash
-python3 -m src.main agent-resume \
- \
+ 4f2c8c6f9c0e4d7c9c7b1b2a3d4e5f67 \
"Continue the previous task and finish the missing parts."
```
-Example:
-
-```bash
-python3 -m src.main agent-resume \
- 4f2c8c6f9c0e4d7c9c7b1b2a3d4e5f67 \
- "Continue building the customer e-commerce project and complete the checkout flow."
-```
-
-Session files are stored under:
-
-```text
-.port_sessions/agent/
-```
-
-You can inspect saved sessions with:
+Inspect saved sessions:
```bash
ls -lt .port_sessions/agent
```
-Important notes:
+> **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.
-- 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
+## ๐งช Testing
-These are handled locally before the model loop:
-
-```bash
-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:
+Run the full test suite:
```bash
python3 -m unittest discover -s tests -v
```
-Optional smoke tests:
+Smoke tests:
```bash
python3 -m src.main agent "/help"
@@ -229,41 +298,29 @@ python3 -m src.main agent \
--cwd .
```
-## Useful Commands
+---
-Workspace summary:
+## ๐ Permission Model
-```bash
-python3 -m src.main summary
-```
+Claw Code Agent uses a **tiered permission system** to keep the agent safe by default:
-Workspace manifest:
+| 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` |
-```bash
-python3 -m src.main manifest
-```
+---
-Mirrored command inventory:
+## โ ๏ธ Disclaimer
-```bash
-python3 -m src.main commands --limit 10
-```
+- This repository is a **Python reimplementation** inspired by the Claude Code npm architecture.
+- It does **not** ship the original npm source.
+- It is **not** affiliated with or endorsed by Anthropic.
-Mirrored tool inventory:
+---
-```bash
-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.
+
+ Built with ๐ Python ยท Powered by ๐ HarnessLab Team.
+