Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/axiomresearchfarm/claudy

Multi-model agentic orchestrator — Claude as boss, ensemble of workers, server-side sandbox + pluggable HITL. AXIOM Research Lab.
https://github.com/axiomresearchfarm/claudy

agentic-ai anthropic axiom axiomresearchfarm bun claude cli open-source typescript

Last synced: 15 days ago
JSON representation

Multi-model agentic orchestrator — Claude as boss, ensemble of workers, server-side sandbox + pluggable HITL. AXIOM Research Lab.

Awesome Lists containing this project

README 

          
# Claudy



> **An AXIOM Research Farm project.** Open source. Public. The ratchet runs forward only.



Multi-model agentic orchestrator. Claude is the boss model; an ensemble of workers (GPT, DeepSeek, Mistral/Devstral, Gemini, Kimi, local Ollama) produces candidates in parallel; a judge picks or synthesizes the best answer. For real coding work, the agent runs in a **sandboxed workspace on a server** and ships you a unified diff to review — your real codebase stays untouched until you explicitly apply.



See [MANIFESTO.md](MANIFESTO.md) for why this exists. See [STRUCTURE.md](STRUCTURE.md) for where things live.



---



## Install (one line)



**macOS · Linux** (arm64 or x64):



```sh

curl -fsSL https://raw.githubusercontent.com/axiomresearchfarm/claudy/main/installer/install.sh | sh

```



What this does:

- Detects your platform (`darwin-arm64`, `darwin-x64`, `linux-x64`, `linux-arm64`)

- Downloads `claudy` + `claudyd` for the **latest GitHub Release** and SHA256-verifies them

- Installs to `~/.claudy/bin/`, symlinks into `/usr/local/bin` (or `~/.local/bin` for non-root)

- Strips the macOS Gatekeeper quarantine bit so unsigned binaries run cleanly

- Registers a daily auto-update unit (launchd on macOS, systemd user timer on Linux)



**Installer options** (pass after `| sh -s --`):



| Flag | Effect |

|---|---|

| `--version v0.3.2` | install a specific release tag instead of latest |

| `--prefix /custom/dir` | install under a different directory (default `~/.claudy`) |

| `--no-update` | skip registering the daily auto-update unit |

| `--uninstall` | remove `~/.claudy/` and the auto-update unit |



Example:



```sh

curl -fsSL https://raw.githubusercontent.com/axiomresearchfarm/claudy/main/installer/install.sh \

  | sh -s -- --version v0.3.2 --no-update

```



**After install**, drop your provider keys into `~/.claudy/.env`:



```sh

cat > ~/.claudy/.env <<'EOF'

ANTHROPIC_API_KEY=...

# optional workers:

# OPENAI_API_KEY=...

# DEEPSEEK_API_KEY=...

# MISTRAL_API_KEY=...

# GEMINI_API_KEY=...

# KIMI_API_KEY=...

EOF

chmod 600 ~/.claudy/.env

```



Then:



```sh

claudy           # interactive agentic REPL

```



### Update later



The daily auto-updater runs at ~04:17 local time. To trigger manually:



```sh

claudy update --check    # see whether a newer version exists

claudy update            # download + atomic swap if newer

```



The updater verifies SHA256 against the release's manifest, then atomic-renames into place. Previous binary is kept as `claudy.prev` for one cycle.



---



## Build from source



If you want to hack on Claudy instead of running the released binary, see [QUICKSTART.md](QUICKSTART.md) — covers `bun install`, dev loop, tests, lint.



---



## Two modes



```

                       ┌────────────────────────┐

   prompt ───▶  REPL ──┤  router → interpreter  ├─▶ workers (parallel) ─▶ judge ─▶ composer ─▶ answer

                       └────────────────────────┘



                       ┌────────────────────────────────────────────────────────────┐

   task  ───▶  CLI ────┤  claudyd (server)                                          │

                       │    sandbox(workspace) → agent loop ↔ HITL channels ↔ user  │

                       │                            ↓                                │

                       │                          review → artifact (diff)           │

                       └────────────────────────────────────────────────────────────┘

                                                 ↓

                                       user applies locally

```



- **Chat REPL** (`claudy`) — fast multi-model ensemble for questions, plans, drafts.

- **Agentic task** (`claudy task ...`) — long-running autonomous work in a server-side sandbox. Emits a unified diff and the shell commands you still need to run yourself.

- **Mobile** (since v0.29.5) — the web UI is a PWA: open `claudyd` in mobile Safari/Chrome and "Add to Home Screen" for a standalone app. See [QUICKSTART.md → Mobile](QUICKSTART.md#mobile-v0295).



## Why server-side sandbox



Your real codebase doesn't change until *you* apply the diff. The agent can hit dead ends, run failed experiments, retry on errors, pause for hours waiting on you — none of it touches your tree. You review one clean patch at the end. This is non-negotiable: it's what makes long-running autonomous agents acceptable.



## HITL is a pluggable interface



The server holds a `HitlBus` with registered channels. Each `HitlChannel` is one adapter — SSE (default, ships connected clients), `StdinChannel` (terminal), and any of `TelegramChannel` / `WebPushChannel` / `FCMChannel` / `SlackChannel` you choose to plug in. The bus fans out the prompt to every channel; whichever channel the user replies on first wins.



Adding a new transport is one file (`class XChannel implements HitlChannel`). No core changes.



This is consistent with the AXIOM Human Interface (AHI) protocol direction — explicit, typed, audit-trail-bearing escalations from machine to human. See the AHI vision doc when the corresponding contract version is published.



## Quick start (from source)



For contributors. End users should use the one-line installer above.



Requires Bun ≥ 1.1.



```bash

bun install

cp .env.example .env       # at least ANTHROPIC_API_KEY

bun run server &           # claudyd on 127.0.0.1:8787

bun run cli                # agentic REPL

# OR

claudy task "rename helper.foo to helper.bar everywhere" --src ./my-repo

```



Single-binary builds:



```bash

bun build packages/cli/src/index.ts    --compile --outfile bin/claudy

bun build packages/server/src/index.ts --compile --outfile bin/claudyd

```



## Architecture



Monorepo, seven packages, each a clean Rust translation target:



| Package | Purpose |

|---|---|

| `@claudy/protocol` | shared types + zod schemas + pipeline/agent events + HitlChannel interface |

| `@claudy/storage` | SQLite layer (projects, sessions, messages, memory, runs, stages) |

| `@claudy/core` | providers (Anthropic/OpenAI/DeepSeek/Mistral/Gemini/Kimi/Ollama), 5-stage pipeline, settings, HitlBus |

| `@claudy/sandbox` | workspace lifecycle, path-jail, shell allowlist, git diff producer, tool execution |

| `@claudy/agent` | tool-use loop with self-recovery, agent tool schemas, HITL gates |

| `@claudy/cli` | `claudy` binary — REPL + `task` subcommand, StdinChannel |

| `@claudy/server` | `claudyd` binary — HTTP+SSE, SSEChannel, agentic endpoints, artifact API |



Dependency graph: strict DAG. `cli`/`server` → `agent` → `sandbox` → `core` → `storage` → `protocol`. No cycles. No package above `protocol` reaches into another for internals.



## Pipeline stages (chat mode)



| Stage | Default model | Responsibility |

|-------|---------------|----------------|

| Router | Claude Haiku | Classify route (trivial / chat / research / plan / code). Pick worker subset. Fast path on trivial. |

| Interpreter | Claude Sonnet | Normalize prompt → typed `TaskSpec`. |

| Workers | parallel ensemble | N workers solve the TaskSpec independently. |

| Judge | Claude Opus | Score candidates, pick winner, optionally emit synthesis hint. |

| Composer | Claude Sonnet | Stream final answer in Claudy's voice. |



## Agentic flow (task mode)



```

client                 server (claudyd)                                 sandbox

  │                        │                                              │

  │ POST /api/runs/agentic │                                              │

  ├───────────────────────▶│ create Workspace (copy ─src or git clone)    │

  │                        ├─────────────────────────────────────────────▶│

  │                        │ agent loop (tool-use)                        │

  │  ◀── SSE: tool_call ───┤  read_file / write_file / edit_file / grep   │

  │  ◀── SSE: tool_result ─┤  list_dir / run_shell (allowlist+HITL) /     │

  │                        │  git_status / task_complete                  │

  │                        │                                              │

  │  ◀── SSE: hitl_request ┤ HitlBus.request() ─▶ all channels (SSE,      │

  │ POST /api/hitl/respond │   Telegram, WebPush, FCM, stdin, …)          │

  │                       ─▶  HitlBus.respond() ─▶ first wins             │

  │                        │                                              │

  │                        │ review loop (judge LLM evaluates diff)       │

  │                        │   ↩ rejected → loop with critique            │

  │                        │   ✓ accepted → finalize                      │

  │                        │                                              │

  │  ◀── SSE: artifact ────┤ produce unified diff vs initial snapshot     │

  │                        │                                              │

  │ writes claudy.patch    │ destroys workspace (unless error)            │

  │ user runs: git apply   │                                              │

```



The architecture supports indefinite pauses. A run can sit in `hitl_blocked` for days waiting on a user reply over any channel; the workspace persists on disk until response or cancellation.



## Open source



Dual-licensed under **MIT** or **Apache-2.0**, at your option. See [LICENSE-MIT](LICENSE-MIT) and [LICENSE-APACHE](LICENSE-APACHE).



This project is part of **AXIOM Research Farm** — open source, public, no private power moats. Contribution rules in [CONTRIBUTING.md](CONTRIBUTING.md).