Content
PyClaudeCode
PyClaudeCode is a Python implementation of a Claude Code-like programming agent, supporting multi-turn conversations, tool calls, file read/write, command execution, permission control, session recovery, context compression, MCP access, and a Claude Code-style terminal interface.
The current package name and CLI are still `my_agent` / `my-agent`. It defaults to using DeepSeek's Anthropic-compatible interface but can also switch to an OpenAI-compatible interface.
## Feature Overview
- Claude Code-style REPL: welcome panel, contextual prompts, streaming output, tool call status, and slash commands.
- Multi-turn tool loops: the model can continuously call tools until it gets the final answer.
- Built-in tools: `read`, `write`, `edit`, `bash`, `glob`, `grep`, `task`.
- Permission modes: `read_only`, `ask`, `allow_all`, `danger`.
- Session management: automatic saving, listing, deletion, and recovery by ID or `latest`.
- Configuration system: supports project-level `.my-agent/settings.json`, user-level `~/.my-agent/settings.json`, and environment variable overrides.
- MCP client: accesses external MCP servers via stdio and exposes MCP tools to the model.
- Hooks and plugins: supports pre- and post-tool use hooks and automatic discovery of custom tools from `~/.my-agent/plugins/`.
- Compatibility fixes: handles Python 3.14 venv `.pth` issues and SOCKS proxy crashes without `socksio`.
## Installation
```bash
cd /Users/myAgent
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env
```
Edit `.env` and fill in your DeepSeek key:
```bash
ANTHROPIC_AUTH_TOKEN=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
ANTHROPIC_MODEL=deepseek-v4-pro[1m]
ANTHROPIC_EFFORT=off
```
If you encounter issues with `my-agent` entry or `python -m my_agent` not finding the source code in a Python 3.14 macOS venv, run:
```bash
scripts/fix_pth.sh
```
This script patches the venv entry and generates a shim package in `site-packages/my_agent` pointing to `src/my_agent`.
## Startup
Enter interactive mode:
```bash
.venv/bin/my-agent
```
Or:
```bash
.venv/bin/python -m my_agent
```
Single query:
```bash
.venv/bin/my-agent "Introduce yourself in one sentence"
```
Pipe input:
```bash
echo "List current directory files" | .venv/bin/my-agent
```
Explicitly enter REPL:
```bash
.venv/bin/my-agent --repl
```
Resume the latest session:
```bash
.venv/bin/my-agent --resume latest
```
Resume a specific session:
```bash
.venv/bin/my-agent --resume <session-id>
```
## Interactive Interface
After starting, you'll see something like:
```text
╭─ ✻ ─────────────────────────────────────────╮
│ Welcome to myAgent Code │
│ cwd: ~/Documents/BuildAgent/myAgent │
│ model: deepseek-v4-pro[1m] │
│ permission: ask session: def37a2a tools: 7│
│ /help for commands Ctrl+D to exit │
╰─────────────────────────────────────────────╯
╭─ ~/Documents/BuildAgent/myAgent (ask)
╰─>
```
Prompt explanation:
- The first line shows the current directory and permission mode.
- The second line `╰─>` is the actual input location.
- The `ask` in parentheses indicates the current permission mode, which is not unique.
Supports backslash line continuation:
```text
╰─> Please analyze this issue and handle it step by step \
... Read README and then check tests
```
## Slash Commands
Type `/help` in REPL to view the command list.
| Command | Description |
|---|---|
| `/help` | View slash commands |
| `/clear` | Clear current conversation history |
| `/compact` | Manually compress context |
| `/permission` | View or switch permission modes |
| `/history` | View message count and estimated tokens |
| `/status` | View current model, tools, session, permissions, etc. |
| `/doctor` | View runtime health summary |
| `/session` | View current session information |
| `/save` | Save current session |
| `/exit` / `/quit` | Exit REPL |
Example of switching permission modes:
```text
/permission read_only
/permission ask
/permission allow_all
/permission danger
```
## Permission Modes
| Mode | Behavior |
|---|---|
| `read_only` | Only allows low-risk operations like reading files and searching |
| `ask` | Default mode; operations like writing files and executing commands require confirmation |
| `allow_all` | Most tool calls are directly allowed |
| `danger` | Skips permission checks, similar to Claude Code's dangerously-skip-permissions |
Specify at startup:
```bash
.venv/bin/my-agent --permission-mode read_only
.venv/bin/my-agent --permission-mode ask
.venv/bin/my-agent --permission-mode allow_all
.venv/bin/my-agent --permission-mode danger
```
Or use environment variables:
```bash
MY_AGENT_PERMISSION_MODE=allow_all .venv/bin/my-agent
```
## Common Commands
View help:
```bash
.venv/bin/my-agent --help
```
View health status:
```bash
.venv/bin/my-agent doctor
```
List sessions:
```bash
.venv/bin/my-agent sessions list
```
Delete a session:
```bash
.venv/bin/my-agent sessions delete <session-id>
```
Specify a model:
```bash
.venv/bin/my-agent --model "deepseek-v4-pro[1m]"
```
Specify inference effort:
```bash
.venv/bin/my-agent --effort low
.venv/bin/my-agent --effort medium
.venv/bin/my-agent --effort high
.venv/bin/my-agent --effort max
.venv/bin/my-agent --effort off
```
Switch to OpenAI-compatible interface:
```bash
.venv/bin/my-agent \
--provider openai \
--base-url https://api.deepseek.com/v1 \
--model deepseek-chat
```
## Configuration
Configuration priority from lowest to highest:
1. Defaults
2. `~/.my-agent/settings.json`
3. Project-level `.my-agent/settings.json`
4. Environment variables
Project configuration example:
```json
{
"permissionMode": "ask",
"model": "deepseek-v4-pro[1m]",
"baseUrl": "https://api.deepseek.com/anthropic",
"effort": "off",
"maxIterations": 20
}
```
Supported environment variables:
| Environment Variable | Corresponding Configuration |
|---|---|
| `ANTHROPIC_AUTH_TOKEN` | API key |
| `ANTHROPIC_MODEL` | `model` |
| `ANTHROPIC_BASE_URL` | `baseUrl` |
| `ANTHROPIC_EFFORT` | `effort` |
| `MY_AGENT_PERMISSION_MODE` | `permissionMode` |
## MCP Configuration
Configure MCP servers in `.my-agent/settings.json` or `~/.my-agent/settings.json`:
```json
{
"mcpServers": {
"filesystem": {
"command": "node",
"args": ["path/to/server.js"]
}
}
}
```
At startup, myAgent initializes the MCP server via stdio, reads `tools/list`, and registers remote tools as:
```text
mcp__<server_name>__<tool_name>
```
MCP parameter schema is converted to Pydantic input models, currently covering required, enum, numeric boundaries, string length, pattern, array items, nullable, `anyOf` / `oneOf`, `const`, and single-level nested objects.
## Hooks
Configure pre- and post-tool use hooks in settings:
```json
{
"hooks": {
"pre_tool_use": ["echo about to run $MY_AGENT_TOOL_NAME"],
"post_tool_use": ["echo completed $MY_AGENT_TOOL_NAME"],
"stop": ["echo done"]
}
}
```
Hooks execute with injected:
- `MY_AGENT_EVENT`
- `MY_AGENT_TOOL_NAME`
- `MY_AGENT_TOOL_INPUT`
## Plugins
Plugin directory:
```text
~/.my-agent/plugins/
```
Place Python files in this directory and export classes conforming to the `Tool` interface. Startup automatically discovers and registers plugins. Registration failures are skipped without affecting the main program's startup.
## Testing
Full testing doesn't require a real API key; use mock clients and local stubs:
```bash
.venv/bin/pytest -q
```
Current baseline:
```text
156 passed
```
Code checks:
```bash
.venv/bin/ruff check .
```
Entry checks:
```bash
.venv/bin/my-agent --help
.venv/bin/python -m my_agent --help
```
## Directory Structure
```text
src/my_agent/
cli.py Typer CLI entry, REPL, slash commands
agent.py Multi-turn agent tool loop
prompt.py System prompt assembly
config.py settings.json/env configuration loading
permission.py Permission strategy and bash risk detection
session.py Session saving, recovery, listing, deletion
compact.py Context compression
hooks.py Pre/post/stop hooks
mcp.py MCP stdio client and MCP tool wrapper
plugins.py User plugin discovery
types.py Anthropic-style internal message protocol
ui/
claude.py Claude Code-style terminal UI
render.py Streaming output and tool status rendering
llm/
anthropic_style.py Anthropic Messages API-compatible client
openai_style.py OpenAI-compatible client
proxy.py SOCKS proxy/httpx client protection
tools/
read.py Read files
write.py Write files
edit.py Replace and edit
bash.py Execute shell commands
glob.py File matching
grep.py Text search
task.py Sub-agent tools
tests/
test_*.py Unit tests and regression tests
scripts/
fix_pth.sh Fix Python 3.14 venv entry and source code loading
```
## FAQ
### `Using SOCKS proxy, but the 'socksio' package is not installed`
Runtime protection is implemented: if a SOCKS proxy is detected but `socksio` is missing, it automatically bypasses the environment proxy to avoid startup crashes.
`pyproject.toml` includes `socksio>=1.0`; reinstall dependencies for native SOCKS support:
```bash
pip install -e ".[dev]"
```
### `.venv/bin/my-agent` fails to start or loads old source code
Execute:
```bash
scripts/fix_pth.sh
```
Then verify:
```bash
.venv/bin/my-agent --help
.venv/bin/python -m my_agent --help
```
### Unable to save session on exit
Sessions are saved to:
```text
~/.my-agent/sessions/
```
If the current runtime environment lacks write permission to this directory, myAgent prints a warning but doesn't let REPL exit with a traceback.
## Related Documents
- [Plan.md](Plan.md): Phase plans and roadmaps
- [taskFinished.md](taskFinished.md): Completed task records
- [ToDo.md](ToDo.md): Test-discovered tech debt and subsequent
