Agenticore

Agenticore

Two modes, one binary. Run a fleet of Claude Code agents that clone repos and ship PRs — or expose any customized Claude Code agent as a real-time, OpenAI-compatible chat completion endpoint with token-by-token thinking and tool deltas. Flip between modes with one environment variable.

[](https://github.com/The-Cloud-Clockwork/agenticore/blob/main/LICENSE) [](https://github.com/The-Cloud-Clockwork/agenticore/actions/workflows/test.yml) [](https://hub.docker.com/r/tccw/agenticore) [](https://ghcr.io/the-cloud-clockwork/charts/agenticore) [](https://pypi.org/project/agenticore/) [](https://python.org)

                          ┌─── AGENT_MODE=false (default) ────────────┐
                          │  FLEET MODE — Orchestrator                 │
                          │  Submit a task, get a PR                   │
                          │                                            │
   MCP / REST / CLI ─────►│  clone repo ──► bespoke worktree           │
                          │       │              │                     │
                          │       └──► claude -p "" ──► auto-PR  │
                          │                              └──► OTEL     │
                          │  KEDA-scaled fleet • work-stealing queue   │
   ┌─────────────┐        └────────────────────────────────────────────┘
   │ agenticore  │
   │   binary    │
   └─────────────┘        ┌─── AGENT_MODE=true ────────────────────────┐
                          │  AGENT MODE — Customized agent endpoint    │
                          │  Drop-in OpenAI chat completion server     │
                          │                                            │
   OpenAI-compatible ────►│  load agent package (system prompt, MCP    │
   chat clients           │    servers, hooks, skills, identity)       │
   (LibreChat,            │                                            │
    OpenWebUI,            │  POST /v1/chat/completions stream=true     │
    LiteLLM,              │       │                                    │
    custom UI,            │       └─► live SSE deltas:                 │
    raw curl -N)          │            thinking_delta (token-by-token) │
                          │            tool_use + tool_result          │
                          │            assistant text                  │
                          │                                            │
                          │  Sticky slash toggles per agent            │
                          │  Fully auditable — wire/disk/Redis layers  │
                          └────────────────────────────────────────────┘

---

Pick a mode

| | Fleet mode (default) | Agent mode (AGENT_MODE=true) | |---|---|---| | What it does | Accepts coding tasks, clones repos, runs Claude Code in bespoke worktrees, opens PRs | Loads a pre-configured Claude Code agent package and exposes it as a chat completion endpoint | | API surface | /jobs REST · run_task MCP tool · agenticore run CLI | /v1/chat/completions — fully OpenAI-compatible, streaming and non-streaming | | Lifecycle | Per-job clone + worktree, discarded after PR | Long-lived agent identity loaded once at container startup | | Scaling | KEDA on Redis queue depth — N pods steal jobs from one queue | One StatefulSet per agent identity; scale horizontally per agent | | Output | A pull request, an OTEL trace, a job result in Redis | Live SSE deltas as chat.completion.chunk JSON, full transcript on disk | | Drop-in for | CI/CD pipelines, MCP-aware editors, internal "fix this" bots | LibreChat, OpenWebUI, LiteLLM model routing, any OpenAI SDK client | | Best for | "We use Claude Code to refactor / fix / generate PRs across many repos" | "We want our chat clients to talk to a customized Claude agent over the OpenAI protocol" |

Both modes share the same binary, the same Docker image, the same Helm chart, the same profile system, the same Redis+file fallback, and the same OTEL trace pipeline. You don't pick at install time. You pick at runtime with one environment variable.

---

Why agenticore

You have Claude Code. You want it to do work for you programmatically. You have two shapes the work tends to take:

1. Headless coding tasks across repos — "fix the auth bug", "add tests for the parser", "refactor this module". You want a fleet that accepts these, clones the right repo, runs Claude in a clean worktree, and opens a PR. → Fleet mode.

1. A customized Claude agent your other tools can talk to — a personal assistant, a domain expert, a finops bot, a docs writer — exposed as an OpenAI-compatible endpoint so LibreChat, OpenWebUI, your LiteLLM router, or any OpenAI SDK client can drop it in as a "model". With real-time streaming of the agent's thinking, tool calls, and answers — not buffered, not batched, not faked. → Agent mode.

Agenticore is one binary that does both. Profiles, hooks, MCP whitelists, Redis state, OTEL traces, Helm chart — all shared between the two modes. Your operations team learns one thing.

---

🟦 FLEET MODE

> Submit a task, get a PR. The original positioning.

MCP Client / REST Client / CLI
            │
            ▼
    ┌── Agenticore (Fleet Mode) ─────────────────────────────────┐
    │   Auth · Router · Job Queue                                │
    │                                                            │
    │   Clone repo ──► Bespoke worktree ──► claude -p "task"     │
    │   (cached)       (locked branch)      (cwd = worktree)     │
    │                                         │                  │
    │                                         ▼                  │
    │                                   Auto-PR (gh)             │
    │                                   Job result → Redis       │
    └──────────────────────┬─────────────────────────────────────┘
                           │
                    OTEL Collector
                    → Langfuse / PostgreSQL

• Accepts tasks from MCP clients, REST, or CLI — same API surface, one port
• Clones and caches repos, serializes concurrent access with distributed locks
• Creates bespoke worktrees — locked before Claude starts, deterministic branch names
• Applies execution profiles — installed into ~/.claude/ at startup via agentihooks
• Spawns claude -p "" in the worktree and opens a PR when it succeeds
• Ships full OTEL traces (prompts, tool calls, token counts) to Langfuse / PostgreSQL
• KEDA autoscaling on Redis queue depth + graceful drain on pod shutdown

Quickstart

# Set credentials
export ANTHROPIC_AUTH_TOKEN=sk-ant-...
export GITHUB_TOKEN=ghp_...

# Start the server
agenticore serve

# Submit a task and wait for the PR URL
agenticore run "fix the null pointer in auth.py" \
  --repo https://github.com/org/repo \
  --wait

REST

# Submit a job (async — returns immediately with job ID)
curl -X POST http://localhost:8200/jobs \
  -H "Content-Type: application/json" \
  -d '{"task":"fix the auth bug","repo_url":"https://github.com/org/repo"}'

# Submit and wait
curl -X POST http://localhost:8200/jobs \
  -H "Content-Type: application/json" \
  -d '{"task":"fix the auth bug","repo_url":"https://github.com/org/repo","wait":true}'

# Inspect
curl http://localhost:8200/jobs/{job_id}
curl "http://localhost:8200/jobs?limit=10&status=running"
curl -X DELETE http://localhost:8200/jobs/{job_id}

MCP tools (fleet mode)

| Tool | Description | |------|-------------| | run_task | Submit a task for Claude Code execution | | get_job | Get status, output, and PR URL for a job | | list_jobs | List recent jobs | | cancel_job | Cancel a running or queued job | | list_profiles | List available execution profiles | | plan_task | Create a read-only implementation plan | | execute_plan | Execute a ready plan as a coding job | | list_worktrees | List all worktrees with age, size, branch, push status | | cleanup_worktrees | Remove specific worktrees (unlock + delete) |

Connect any MCP client at http://localhost:8200/mcp (Streamable HTTP) or /sse (legacy SSE).

---

🟩 AGENT MODE

> One environment variable. Now you have a customized Claude agent talking the OpenAI protocol with real-time thinking + tool streaming.

        AGENT_MODE=true + AGENT_MODE_PACKAGE_DIR=./my-agent-package
                                        │
                                        ▼
  ┌── Agenticore (Agent Mode) ──────────────────────────────────────┐
  │                                                                 │
  │   Load package once at startup:                                 │
  │     ├─ system.md (identity, instructions)                       │
  │     ├─ .claude/ (settings, hooks, skills, agents)               │
  │     └─ .mcp.json (tool servers this agent can call)             │
  │                                                                 │
  │   POST /v1/chat/completions stream=true                         │
  │     │                                                           │
  │     ├─ strip slash tokens (server-side, deterministic)          │
  │     ├─ load sticky visibility config from Redis                 │
  │     ├─ spawn claude --output-format stream-json                 │
  │     │                  --include-partial-messages               │
  │     ├─ read claude stdout line-by-line                          │
  │     │     thinking_delta  → delta.reasoning_content (live)      │
  │     │     text_delta      → delta.content (live)                │
  │     │     tool_use_block  → ```tool_use:NAME fenced block       │
  │     │     tool_result     → ```tool_result fenced block         │
  │     └─ flush each chunk to the open HTTP connection             │
  │                                                                 │
  └─────────────────────────────────────────────────────────────────┘

Drop-in for any OpenAI-compatible client. Because the endpoint speaks /v1/chat/completions and emits standard chat.completion.chunk JSON over SSE, you can register an agenticore-backed agent as an "OpenAI custom model" inside:

• LibreChat — add as a custom OpenAI endpoint, pick from the model dropdown
• OpenWebUI — same pattern
• LiteLLM — register as openai/ with api_base=http://:8200/v1, then route any LiteLLM client at it
• OpenAI SDK (Python, JS, Go, Rust) — OpenAI(base_url="http://:8200/v1") and call chat.completions.create(...) exactly like you would against api.openai.com
• curl -N — raw SSE works fine

Killer features

• Real-time SSE streaming, fully auditable, fully traceable. Thinking blocks stream token-by-token as the model generates them. Tool calls and results stream live as the agent invokes them. Assistant text streams progressively. Nothing is buffered to the end of the turn. The streaming hot path reads claude's stdout directly via --output-format stream-json --verbose --include-partial-messages — no transcript polling, no Redis indirection, no JSONL flush race.
• Thinking renders in delta.reasoning_content — separate reasoning panel in reasoning-aware clients (LibreChat, OpenWebUI), with x_agenticore_event_type="thinking" for custom clients that want explicit tagging.
• Tool calls render as fenced markdown blocks — `tool_use:NAME paired with `tool_result below it. Deliberately not OpenAI's delta.tool_calls schema, which would make chat clients try to client-execute the tool and fail with "Tool not found".
• Sticky per-agent visibility toggles intercepted server-side, before claude ever sees the prompt:
• /show-thinking / /hide-thinking
• /show-tools / /hide-tools
• /show-all / /hide-all
• /stream-status (returns the current config inline as a meta SSE event)
• Multi-turn aware — toggle detection runs against the last user message, not the flattened history, so slash commands work on turn 2+. Toggle-only requests (e.g. just /show-all) return inline status without spawning claude — zero token cost.
• Three-layer observation — every visible event reaches (1) the client over the wire, (2) claude's transcript JSONL on disk, and (3) optionally the Redis bus (non-streaming path) for cross-process subscribers. Cross-validate all three with tests/smoke/verify_streaming_pipeline.sh .
• Async completion queue for fire-and-forget — wait=false pushes to Redis, a worker picks it up, poll GET /completions/{uuid}.
• Session continuity — resume a conversation across requests via the external correlation UUID.
• Redis+file fallback — works without Redis (inline execution, file-based state).

Quickstart

# Start the server in agent mode pointing at your agent package
AGENT_MODE=true \
AGENT_MODE_PACKAGE_DIR=./my-agent-package \
AGENTICORE_TRANSPORT=sse \
agenticore serve

# Toggle visibility once (sticky per agent — persists in Redis)
curl -sN http://localhost:8200/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"sonnet","stream":true,"messages":[{"role":"user","content":"/show-all"}]}'

# Now have a real conversation — watch thinking tokens + tool calls stream live
curl -sN http://localhost:8200/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"sonnet","stream":true,"messages":[
        {"role":"user","content":"is 17077 prime? think hard, then list any files in /tmp"}
      ]}'

# Non-streaming JSON (no slash tokens needed)
curl -X POST http://localhost:8200/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"sonnet","messages":[{"role":"user","content":"hello"}]}'

Drop into LibreChat

# librechat.yaml
endpoints:
  custom:
    - name: "Agenticore Agents"
      apiKey: "${LITELLM_API_KEY}"
      baseURL: "http://litellm.your-cluster.svc:4000/v1"
      models:
        fetch: true
      titleConvo: true

Register the agent in LiteLLM as a model pointing at the agenticore pod:

# Via LiteLLM admin (or the litellm_tools MCP)
model_name: my-agent
litellm_params:
  model: openai/my-agent
  api_base: http://my-agent.namespace.svc:8200/v1

Now my-agent shows up in LibreChat's model picker. Token-by-token thinking renders in the reasoning panel. Tool calls stream live as fenced markdown blocks.

Drop into the OpenAI SDK

from openai import OpenAI

client = OpenAI(base_url="http://my-agent.namespace.svc:8200/v1", api_key="n/a")

stream = client.chat.completions.create(
    model="sonnet",
    stream=True,
    messages=[
        {"role": "user", "content": "/show-all explain how an OS scheduler works step by step"},
    ],
)
for chunk in stream:
    delta = chunk.choices[0].delta
    if reasoning := getattr(delta, "reasoning_content", None) or delta.model_dump().get("reasoning_content"):
        print(f"[think] {reasoning}", end="", flush=True)
    elif delta.content:
        print(delta.content, end="", flush=True)

Full reference: [SSE Streaming docs](docs/reference/sse-streaming.md) · [Self-test walkthrough](docs/getting-started/test-streaming.md) · [Agent Mode architecture](docs/architecture/agent-mode.md)

---

Shared infrastructure (both modes)

Everything below applies to both Fleet mode and Agent mode. Same Docker image, same Helm chart, same env vars, same Redis schema.

Install

pip install agenticore

Or from source:

git clone https://github.com/The-Cloud-Clockwork/agenticore.git
cd agenticore
pip install -e .

Profiles

Profiles are directory packages that configure how Claude Code runs. Each profile is a self-contained .claude/ tree installed into ~/.claude/ at container startup by agentihooks global. Claude Code reads from ~/.claude/ by default.

/{name}/
├── profile.yml          ← Agenticore metadata (model, turns, auto_pr, timeout…)
├──

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [the-cloud-clockwork](https://github.com/the-cloud-clockwork)
- **Source:** [the-cloud-clockwork/agenticore](https://github.com/the-cloud-clockwork/agenticore)
- **License:** MIT
- **Homepage:** https://the-cloud-clock-work.github.io/agenticore/

Install and usage instructions live in the source repository linked above.