# Claude Code Manager WAN

An ISLI v2.0 skill that lets ISLI agents (Hermes, OpenClaw, ISLI Core) dispatch natural-language coding and terminal tasks to a locally-installed **Claude Code** CLI. It also exposes those capabilities through an **MCP bridge** so any MCP client can list and invoke the tools.

## What it does

- **One-shot execution** — run a single task in a workspace directory.
- **Persistent sessions** — start a long-lived Claude Code process, send follow-up tasks, and inspect its output.
- **MCP bridge** — expose `tools/list` and `tools/call` endpoints compatible with [mcp-cli-adapter](https://github.com/inercia/mcp-cli-adapter) / MCPShell.

## ISLI v2.0 endpoints

| Method | Path | Tool name |
|--------|------|-----------|
| GET | `/health` | health check |
| GET | `/.well-known/isli-manifest` | manifest |
| POST | `/execute` | `claude_code_execute` |
| POST | `/session/start` | `claude_code_session_start` |
| POST | `/session/send` | `claude_code_session_send` |
| POST | `/session/status` | `claude_code_session_status` |
| POST | `/session/stop` | `claude_code_session_stop` |
| POST | `/mcp/v1/tools/list` | `mcp_tools_list` |
| POST | `/mcp/v1/tools/call` | `mcp_tools_call` |

All endpoints except `/health` and `/.well-known/isli-manifest` require a valid `X-Internal-Auth` JWT signed with `JWT_SECRET`.

## Quick start

### 1. Install Claude Code locally

This skill assumes the `claude` binary is available on the host. Install or locate it, then note the path.

### 2. Build and run the skill

```bash
docker build -t claude-code-manager-wan .

docker run -d \
  --name claude-code-manager-wan \
  --network isli_default \
  -p 8000:8000 \
  -e JWT_SECRET=your-jwt-secret \
  -e CLAUDE_CODE_PATH=/usr/local/bin/claude \
  -e CLAUDE_CODE_TIMEOUT_SECONDS=120 \
  -v /path/to/claude:/usr/local/bin/claude:ro \
  -v /path/to/your/workspaces:/workspaces:rw \
  claude-code-manager-wan
```

### 3. Test health

```bash
curl http://localhost:8000/health
```

### 4. Execute a task

```bash
curl -X POST http://localhost:8000/execute \
  -H "Content-Type: application/json" \
  -H "X-Internal-Auth: $(python -c "import jwt; print(jwt.encode({}, 'your-jwt-secret', algorithm='HS256'))")" \
  -d '{
    "workspace": "/workspaces/my-project",
    "task": "List the files in this directory",
    "allow_write": false,
    "timeout_seconds": 60
  }'
```

## Docker notes

- **Claude Code binary**: The image does not include Claude Code. Mount a Linux-compatible `claude` binary (or a wrapper script) into the container and set `CLAUDE_CODE_PATH`. A Windows `.exe` will not run inside the Linux container.
- **Port conflicts**: If `localhost:8000` is already in use, map a different host port (e.g., `-p 8001:8000`) and adjust your test URLs.
- **Workspaces**: Mount the directories you want Claude Code to operate on as volumes. The skill validates that the workspace exists and, if `ALLOWED_WORKSPACES` is set, that it is within an allowed prefix.
- **Integration test fixtures**: The `tests/mock-claude*` files provide a minimal fake Claude CLI for validating the skill in CI/Docker without a real Anthropic account.
- **Custom launch command**: Use `CLAUDE_CODE_LAUNCH_COMMAND` to wrap or proxy the binary. The skill splits the command with shlex and appends its own arguments (`--dangerously-skip-permissions` if `allow_write=true`, `-p <task>` for one-shot mode). Examples:
  - `ollama launch claude --model glm-5.2:cloud`
  - `/usr/local/bin/claude-wrapper --agent hermes`

## Environment variables

| Variable | Default | Description |
|----------|---------|-------------|
| `JWT_SECRET` | — | **Required.** Secret used to verify `X-Internal-Auth` JWTs from ISLI Core. |
| `CLAUDE_CODE_PATH` | `claude` | Path to the Claude Code binary. Used when `CLAUDE_CODE_LAUNCH_COMMAND` is not set. |
| `CLAUDE_CODE_LAUNCH_COMMAND` | — | **Optional full launcher command.** Overrides `CLAUDE_CODE_PATH` and lets you wrap or replace the binary invocation, e.g. `ollama launch claude --model glm-5.2:cloud`. |
| `CLAUDE_CODE_TIMEOUT_SECONDS` | `120` | Default subprocess timeout. |
| `ALLOWED_WORKSPACES` | — | Optional comma-separated list of allowed workspace directory prefixes. Empty = no restriction. |
| `MAX_CONCURRENT_SESSIONS` | `10` | Maximum number of persistent Claude Code sessions. |
| `LOG_LEVEL` | `INFO` | Logging level. |

## Persistent sessions

Start a session:

```bash
curl -X POST http://localhost:8000/session/start \
  -H "Content-Type: application/json" \
  -H "X-Internal-Auth: ..." \
  -d '{"session_id":"proj-a","workspace":"/workspaces/my-project","allow_write":true}'
```

Send follow-up tasks:

```bash
curl -X POST http://localhost:8000/session/send \
  -H "Content-Type: application/json" \
  -H "X-Internal-Auth: ..." \
  -d '{"session_id":"proj-a","task":"Create a README.md"}'
```

Check status:

```bash
curl -X POST http://localhost:8000/session/status \
  -H "Content-Type: application/json" \
  -H "X-Internal-Auth: ..." \
  -d '{"session_id":"proj-a","tail_lines":50}'
```

Stop:

```bash
curl -X POST http://localhost:8000/session/stop \
  -H "Content-Type: application/json" \
  -H "X-Internal-Auth: ..." \
  -d '{"session_id":"proj-a","force":false}'
```

## MCP bridge

The `/mcp/v1/tools/list` and `/mcp/v1/tools/call` endpoints follow the Model Context Protocol shape. Configure Hermes or OpenClaw with `mcp-cli-adapter` pointing to this skill's HTTP endpoint and passing the `X-Internal-Auth` header.

Example `tools/list` response:

```json
{
  "tools": [
    {
      "name": "claude_code_execute",
      "description": "Run a one-shot natural-language task through Claude Code...",
      "inputSchema": { "type": "object", "required": ["workspace", "task"], "properties": { ... } }
    }
  ]
}
```

Example `tools/call`:

```bash
curl -X POST http://localhost:8000/mcp/v1/tools/call \
  -H "Content-Type: application/json" \
  -H "X-Internal-Auth: ..." \
  -d '{
    "name": "claude_code_execute",
    "arguments": {
      "workspace": "/workspaces/my-project",
      "task": "Show git status",
      "allow_write": false
    }
  }'
```

## Security

- `allow_write` defaults to `false`; set it to `true` only when the agent needs to edit files or run git commands.
- Use `ALLOWED_WORKSPACES` to restrict which directories Claude Code can touch.
- Never expose `JWT_SECRET` or the skill port publicly.
- The `--dangerously-skip-permissions` Claude Code flag is used only when `allow_write=true`.

## Registering in ISLI

Add this entry to `medelmouhajir/isli-skills-registry/index.json`:

```json
{
  "id": "claude-code-manager-wan",
  "name": "Claude Code Manager WAN",
  "description": "Control Claude Code from ISLI agents. Dispatch one-shot and persistent terminal/coding tasks, and expose them via an MCP bridge.",
  "author": "ISLI AI",
  "git_url": "https://github.com/medelmouhajir/claude-code-manager-wan",
  "tags": ["automation", "claude-code", "mcp", "terminal", "coding"],
  "version": "v1.0.0"
}
```

## License

MIT