{"id":48659145,"url":"https://github.com/akougkas/pancode","last_synced_at":"2026-04-10T09:28:43.757Z","repository":{"id":341829981,"uuid":"1170329520","full_name":"akougkas/pancode","owner":"akougkas","description":"PanCode is a fast open-source runtime for autonomous multi-agent workflows. Each agent in the fleet runs its own model and provider, shares context through a registry, and operates within configurable safety constraints. Multi-model. Multi-provider. Self-evolving. Built on Bun.","archived":false,"fork":false,"pushed_at":"2026-04-04T13:41:36.000Z","size":2318,"stargazers_count":0,"open_issues_count":60,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-04T15:59:56.193Z","etag":null,"topics":["agent-orchestration","agentic-ai","ai-fleet","ai-runtime","autonomous-agents","bun","code-automation","developer-tools","heterogeneous-agents","llm-orchestration","multi-agent","multi-model","parallel-agents","self-evolving-ai"],"latest_commit_sha":null,"homepage":"https://pancode.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/akougkas.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-02T02:09:13.000Z","updated_at":"2026-04-04T13:41:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/akougkas/pancode","commit_stats":null,"previous_names":["akougkas/pancode"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/akougkas/pancode","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akougkas%2Fpancode","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akougkas%2Fpancode/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akougkas%2Fpancode/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akougkas%2Fpancode/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/akougkas","download_url":"https://codeload.github.com/akougkas/pancode/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akougkas%2Fpancode/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31636641,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-10T07:40:12.752Z","status":"ssl_error","status_checked_at":"2026-04-10T07:40:11.664Z","response_time":98,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-orchestration","agentic-ai","ai-fleet","ai-runtime","autonomous-agents","bun","code-automation","developer-tools","heterogeneous-agents","llm-orchestration","multi-agent","multi-model","parallel-agents","self-evolving-ai"],"created_at":"2026-04-10T09:28:40.657Z","updated_at":"2026-04-10T09:28:43.748Z","avatar_url":"https://github.com/akougkas.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PanCode\n\n[![Version](https://img.shields.io/badge/version-0.3.0--exp-blue)](https://github.com/akougkas/pancode)\n[![License](https://img.shields.io/badge/license-Apache%202.0-green)](./LICENSE)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org/)\n[![Experimental](https://img.shields.io/badge/status-experimental%20preview-orange)](https://github.com/akougkas/pancode)\n\n**One Runtime. Every Agent.**\n\nPanCode is a composable multi-agent runtime for software engineering. It orchestrates coding agents the way Kubernetes orchestrates containers. Every coding agent on your machine becomes a managed, observable, coordinated worker dispatched by capability, not by backend.\n\nPanCode is not a chatbot. It is not a plugin or a cloud service. It is the orchestration layer above Claude Code, Codex CLI, Gemini CLI, and local inference workers.\n\n\u003e **Experimental Preview (v0.3.0-exp)**\n\u003e\n\u003e PanCode ships the runtime early and on purpose. The APIs may shift. The architecture and control-plane thesis will not. Built in the open under Apache 2.0.\n\n---\n\n## Table of Contents\n\n- [Why PanCode](#why-pancode)\n- [How It Works](#how-it-works)\n- [Quick Start](#quick-start)\n- [The Pan Taxonomy](#the-pan-taxonomy)\n- [Architecture](#architecture)\n- [Orchestrator Modes](#orchestrator-modes)\n- [Agent Fleet](#agent-fleet)\n- [Runtime Adapters](#runtime-adapters)\n- [Configuration](#configuration)\n- [Local AI Setup](#local-ai-setup)\n- [Roadmap](#roadmap)\n- [Development](#development)\n- [Contributing](#contributing)\n- [License](#license)\n\n---\n\n## Why PanCode\n\nThe coding agent landscape is fragmented. Claude Code, Codex, Gemini CLI, OpenCode, Copilot CLI, and dozens of local models all speak different protocols, report different metrics, and enforce different safety boundaries. Running them together means writing glue code, losing observability, and accepting inconsistent safety guarantees.\n\nPanCode solves this by providing one runtime that discovers, composes, and coordinates any coding agent through a unified safety model, dispatch system, and observability layer. You get:\n\n- **One dispatch pipeline** across all agents. Same admission gates, same receipts, same cost tracking.\n- **One safety model** enforced structurally. Mode gating controls visibility. Policy gating controls permissions. No agent bypasses the boundary.\n- **One observability surface.** Cost, tokens, turns, wall time, and reproducibility receipts from one terminal session.\n- **Fleet-scale thinking.** Worker pools, heartbeat monitoring, batch dispatch, chain dispatch, and staggered launches. Engineered for 10+ concurrent agents today with a path to 1000+.\n\nPanCode is engineered with HPC DNA and proper platform design principles. Subprocess isolation is absolute. Every worker runs as a separate OS process. Architectural boundaries are enforced at build time. State persistence uses atomic writes. The system is designed like infrastructure, not like a chat window.\n\n---\n\n## How It Works\n\nPanCode follows a deliberate four-step operational loop:\n\n```\nDiscover ──▸ Configure ──▸ Dispatch ──▸ Observe\n```\n\n**Discover.** On boot, PanCode scans your machine for installed coding agents and local inference endpoints. Claude Code, Codex, Gemini CLI, OpenCode, Copilot CLI, LM Studio, Ollama, and llama.cpp are detected automatically.\n\n**Configure.** Speak to Panos, the orchestrator, in natural language. \"Switch to full-auto safety.\" \"Set the budget ceiling to 5 dollars.\" \"Use the local preset.\" Configuration is conversational, keyboard-accelerated, and persisted to disk.\n\n**Dispatch.** Ask for work. Panos decomposes tasks, selects agents by capability and tier, and dispatches workers as isolated subprocesses. Single tasks, parallel batches, and sequential chains are all first-class dispatch primitives.\n\n**Observe.** Every dispatch produces a reproducibility receipt. Cost, tokens, turns, wall time, and action classifications are tracked per run. The TUI dashboard shows live worker status, context window consumption by category, and session economics.\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- Node.js 20 or newer\n- npm\n- `tmux` (PanCode runs inside tmux for session persistence)\n- At least one provider: local (LM Studio, Ollama, llama.cpp) or cloud (Anthropic, OpenAI)\n\n### Install\n\n```bash\nnpm install -g pancode@exp\n```\n\nOr build from source:\n\n```bash\ngit clone https://github.com/akougkas/pancode.git\ncd pancode\nnpm install\nnpm run build\nnpm link\n```\n\n### Launch\n\n```bash\npancode                    # Start a new tmux session\npancode --preset local     # Start with local inference\npancode up                 # Reattach to existing session\npancode down               # Stop the current session\npancode sessions           # List all running sessions\n```\n\n### First Interaction\n\nOnce inside a PanCode session:\n\n```\nShift+Tab       Cycle modes: Plan → Build → Review\nAlt+A           Enter Admin (God Mode)\nCtrl+Y          Cycle safety levels\n\n/agents         View the agent fleet\n/runtimes       View discovered runtime adapters\n/workers        View the worker pool with scores\n/modes          View current mode and tool access\n/help           Full command reference\n```\n\nAsk Panos to dispatch work:\n\n```\n\"Scout the src/ directory for architecture violations\"\n\"Review the last 3 commits for security issues\"\n\"Build a REST endpoint for user authentication\"\n```\n\n---\n\n## The Pan Taxonomy\n\nPanCode is universal across six dimensions. Each \"Pan-\" prefix represents a dimension of composability that no single agent provides alone.\n\n| Dimension | What It Means |\n|-----------|---------------|\n| **Pan-provider** | Route local engines, frontier APIs, or hybrid fleets without standardizing on a single vendor. |\n| **Pan-model** | Match model capability, latency, and cost to the task. Tier classification prevents mismatched assignments. |\n| **Pan-runtime** | Run native workers, SDK-backed agents, or headless CLIs under one dispatch contract. |\n| **Pan-agent** | Discover installed coding agents automatically. Operate them as a coordinated fleet. |\n| **Pan-safety** | Apply a shared safety model across all runtimes. Mode gates visibility. Policy gates permissions. |\n| **Pan-observe** | Track cost, tokens, turns, receipts, and runtime status from one terminal session. |\n\n---\n\n## Architecture\n\n```\n┌──────────────────────────────────────────────────────────────┐\n│                       PanCode Runtime                        │\n│                                                              │\n│  src/core/          Config, modes, bus, presets, validation  │\n│                                                              │\n│  src/domains/       10 composable domains                    │\n│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌──────────┐          │\n│  │ safety  │ │ session │ │ agents  │ │ prompts  │          │\n│  └─────────┘ └─────────┘ └─────────┘ └──────────┘          │\n│  ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌──────────┐         │\n│  │dispatch │ │ observ. │ │schedule │ │panconfig │         │\n│  └─────────┘ └─────────┘ └──────────┘ └──────────┘         │\n│  ┌─────────┐ ┌─────────┐                                    │\n│  │intellig.│ │   ui    │                                    │\n│  └─────────┘ └─────────┘                                    │\n│                                                              │\n│  src/engine/       SOLE SDK IMPORT BOUNDARY                  │\n│  ┌──────────────────────────────────────────────────────┐    │\n│  │ SDK wrappers │ Session │ Tools │ TUI engine │ Types  │    │\n│  │ runtimes/                                            │    │\n│  │   pi-runtime.ts          Native runtime (full ctrl)  │    │\n│  │   claude-sdk.ts          Claude Agent SDK adapter    │    │\n│  │   adapters/              5 CLI adapters              │    │\n│  └──────────────────────────────────────────────────────┘    │\n│                                                              │\n│  src/worker/       ISOLATED SUBPROCESS (no domain imports)   │\n│  ┌──────────────────────────────────────────────────────┐    │\n│  │ Subprocess entry │ Safety extension │ Heartbeat      │    │\n│  └──────────────────────────────────────────────────────┘    │\n└──────────────────────────────────────────────────────────────┘\n```\n\n**Three hard boundaries enforced at build time:**\n\n1. **Engine boundary.** Only `src/engine/` imports from vendored SDK packages. No file outside this directory may reference them. Enforced by `check-boundaries`.\n2. **Worker isolation.** `src/worker/` cannot import from `src/domains/`. Every worker runs as a separate OS process with no shared memory, event loop, or file descriptors.\n3. **Domain independence.** Each domain owns its state. Cross-domain communication flows exclusively through `SafeEventBus`. No domain mutates another domain's state.\n\n---\n\n## Orchestrator Modes\n\nPanCode operates in one of four orchestrator modes. Modes are structural gates that control what the orchestrator can see and do. They are orthogonal to safety levels (suggest, auto-edit, full-auto) which control what is permitted.\n\n| Mode | Dispatch | Mutations | Use Case |\n|------|----------|-----------|----------|\n| **Admin** | Yes | Config only | System management, diagnostics, fleet configuration |\n| **Plan** | No | No | Analyze codebase, design approach, build execution plan |\n| **Build** | Yes | Yes | Full dispatch. Workers implement, test, and review code. |\n| **Review** | Yes | No | Quality checks. Readonly reviewers analyze code without mutation. |\n\n`Shift+Tab` cycles Plan, Build, Review. `Alt+A` enters Admin (God Mode).\n\n### Tool Gating by Mode\n\n| Tool Category | Admin | Plan | Build | Review |\n|---------------|-------|------|-------|--------|\n| Read, search, explore | Yes | Yes | Yes | Yes |\n| File write, edit | No | No | Yes | No |\n| Dispatch workers | Yes | No | Yes | Yes (readonly only) |\n| Configuration mutation | Yes | No | No | No |\n\n---\n\n## Agent Fleet\n\nPanCode ships 7 default agents. Each has a dedicated system prompt, tool allowlist, tier classification, and autonomy level. Agents are defined in `~/.pancode/panagents.yaml` and can be customized or extended.\n\n| Agent | Role | Readonly | Tier | Speed |\n|-------|------|----------|------|-------|\n| **scout** | Fast codebase reconnaissance | Yes | any | fast |\n| **planner** | Architecture and implementation planning | Yes | frontier | thorough |\n| **builder** | Code generation and implementation | No | mid | balanced |\n| **reviewer** | Code review and quality analysis | Yes | mid | thorough |\n| **plan-reviewer** | Plan critic and feasibility validation | Yes | mid | thorough |\n| **documenter** | Documentation generation | No | any | balanced |\n| **red-team** | Security and adversarial testing | Yes | mid | thorough |\n\nAdd custom agents by editing `panagents.yaml`. Assign CLI runtime agents with `runtime: cli:claude-code` on any agent entry. Model references support `${PANCODE_WORKER_MODEL}` expansion.\n\n---\n\n## Runtime Adapters\n\nPanCode supports three tiers of agent integration. Every agent, regardless of backend, produces a worker with the same dispatch, safety, and observability guarantees.\n\n| Tier | Runtime | Integration Depth |\n|------|---------|-------------------|\n| **Native** | Pi SDK | Full: prompts, tools, model, safety, events |\n| **SDK** | Claude Agent SDK | Deep: structured I/O, tool hooks, session pooling |\n| **CLI** | Claude Code, Codex, Gemini CLI, OpenCode, Copilot CLI | Task + CWD + system prompt over subprocess |\n\nRuntime discovery runs at boot, scanning PATH for known binaries. Detected runtimes register automatically. Use `/runtimes` to see what was discovered.\n\n---\n\n## Configuration\n\nPanCode is configured conversationally. Speak to Panos in natural language or use keyboard shortcuts for fast toggles.\n\n| Method | Example |\n|--------|---------|\n| **Natural language** | \"Switch to full-auto safety\" or \"set budget to 5 dollars\" |\n| **Keyboard** | `Shift+Tab` (modes), `Ctrl+Y` (safety), `Alt+A` (admin) |\n| **Slash commands** | `/modes`, `/safety`, `/settings`, `/theme` (view and apply) |\n| **Presets** | `pancode --preset local` or `/preset` inside a session |\n\n### Configuration Files\n\nAll user configuration lives under `~/.pancode/`:\n\n| File | Purpose |\n|------|---------|\n| `panagents.yaml` | Agent fleet definitions |\n| `panpresets.yaml` | Named boot presets |\n| `pansafety.yaml` | Custom safety rules (path restrictions, bash pattern blocks) |\n| `settings.json` | Persisted user preferences |\n\n### Presets\n\nBoot presets configure model, reasoning, and safety in a single named profile.\n\n| Preset | Description |\n|--------|-------------|\n| `local` | Local inference via homelab engines |\n| `openai` | OpenAI models (edit model IDs to match your subscription) |\n| `openai-max` | OpenAI with high reasoning and full-auto safety |\n| `hybrid` | Local orchestrator with remote workers |\n\n```bash\npancode --preset local\n```\n\n### Key Environment Variables\n\n| Variable | Purpose | Default |\n|----------|---------|---------|\n| `PANCODE_MODEL` | Orchestrator model | (from .env or preset) |\n| `PANCODE_WORKER_MODEL` | Default worker model | (from .env or preset) |\n| `PANCODE_SCOUT_MODEL` | Shadow scout model | (from .env or preset) |\n| `PANCODE_SAFETY` | Autonomy: suggest, auto-edit, full-auto | `auto-edit` |\n| `PANCODE_REASONING` | Reasoning: off, minimal, low, medium, high, xhigh | `medium` |\n| `PANCODE_BUDGET_CEILING` | Session cost ceiling in dollars | `10.0` |\n| `PANCODE_DISPATCH_MAX_DEPTH` | Dispatch recursion limit | `2` |\n| `PANCODE_NODE_CONCURRENCY` | Max concurrent workers per node | `4` |\n\nFull reference: [pancode.dev](https://pancode.dev)\n\n---\n\n## Local AI Setup\n\nPanCode discovers local inference endpoints automatically. Start your preferred engine and PanCode will find it.\n\n### LM Studio\n\n```bash\n# Start LM Studio, load a model, enable the server on port 1234\nexport PANCODE_WORKER_MODEL=lmstudio/qwen3.5-35b-a3b\npancode\n```\n\n### Ollama\n\n```bash\nollama serve\nollama pull qwen3:8b\nexport PANCODE_WORKER_MODEL=ollama/qwen3:8b\npancode\n```\n\n### llama.cpp\n\n```bash\nllama-server -m model.gguf --port 8080\nexport PANCODE_WORKER_MODEL=llamacpp/model\npancode\n```\n\nPanCode also discovers remote homelab nodes. Set `PANCODE_LOCAL_MACHINES=192.168.86.143:1234,192.168.86.141:8080` to add endpoints on other machines.\n\n---\n\n## Roadmap\n\nPanCode is growing daily. The architecture is locked. The feature surface is expanding.\n\n**Near-term:**\n- Multi-node fleet dispatch over SSH\n- Adaptive concurrency based on compute, inference, and budget constraints\n- Headless execution mode for CI/CD pipelines (`pancode run --headless`)\n- Post-dispatch verification gates with automated retry\n\n**Medium-term:**\n- SDK agent adapters (Claude Agent SDK, OpenAI Agents SDK, Mastra)\n- SQLite persistence layer replacing JSON state files\n- Dynamic per-capability model routing\n- Provider resilience matrix with circuit breakers\n\n**Long-term:**\n- Agent marketplace with installable skill packs\n- REST API daemon with SSE events\n- Runtime tool forging in sandboxed V8 contexts\n- Speculative dispatch with multi-replica racing\n\nNo dates or timelines are promised. Track progress on [GitHub Issues](https://github.com/akougkas/pancode/issues).\n\n---\n\n## Development\n\n### Build\n\n```bash\nnpm run build              # Production build (SDK packages + tsup)\nnpm run dev                # Dev mode (tsx, skips tmux)\nnpm run typecheck          # TypeScript strict + boundary audit + prompt validation\nnpm run check-boundaries   # Engine and worker isolation enforcement\nnpm run lint               # Biome linter\nnpm run smoke-test         # Baseline verification test\n```\n\n### Code Style\n\n- TypeScript 5.7 strict mode. No `any` unless absolutely necessary.\n- Biome: 120-character lines, 2-space indent, double quotes, semicolons always.\n- Conventional Commits: `feat(scope):`, `fix(scope):`, `docs:`, `chore:`.\n- Atomic file writes (temp + rename) for all state persistence.\n\n---\n\n## Contributing\n\nContributions are welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.\n\nPanCode is pure open source under Apache 2.0. No CLA required.\n\n---\n\n## License\n\n[Apache 2.0](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakougkas%2Fpancode","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fakougkas%2Fpancode","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakougkas%2Fpancode/lists"}