{"id":51149881,"url":"https://github.com/codethread/pandoras-box","last_synced_at":"2026-06-26T05:04:15.083Z","repository":{"id":355233288,"uuid":"1226806058","full_name":"codethread/pandoras-box","owner":"codethread","description":"yet another agent orchestrator","archived":false,"fork":false,"pushed_at":"2026-06-17T18:48:33.000Z","size":4764,"stargazers_count":0,"open_issues_count":8,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-17T20:26:57.959Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codethread.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"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-05-01T21:20:18.000Z","updated_at":"2026-06-17T18:49:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/codethread/pandoras-box","commit_stats":null,"previous_names":["codethread/pithos","codethread/pandoras-box"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/codethread/pandoras-box","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codethread%2Fpandoras-box","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codethread%2Fpandoras-box/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codethread%2Fpandoras-box/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codethread%2Fpandoras-box/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codethread","download_url":"https://codeload.github.com/codethread/pandoras-box/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codethread%2Fpandoras-box/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34803680,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-26T02:00:06.560Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2026-06-26T05:04:10.781Z","updated_at":"2026-06-26T05:04:15.047Z","avatar_url":"https://github.com/codethread.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pandora's Box\n\n\u003e A local control plane where you talk to **Pandora** and she releases her Evils — Envy, Toil, Greed, War — to do the work.\n\n## About\n\nYou chat with **Pandora** in her tmux session. She queues up work; her Evils\nclaim it, run in their own Claude or Pi harness sessions, and report back.\nYou don't run shell commands in the loop — Pandora does.\n\n**Key features**\n\n- **One conversation, many runs.** Pandora is the one you talk to. Her Evils\n  come and go as work demands.\n- **Durable memory.** Every task, design, and decision is stored. Crash\n  recovery and audit are free, and Pandora gets sharper as context\n  accumulates.\n- **Replaceable harnesses.** Claude Code and Pi both work today.\n- **tmux-based control plane.** HITL Evils live in named tmux sessions you\n  can attach to.\n\n**The Evils**\n\n| Evil    | Mode | Claims              | Role                                                     |\n| ------- | ---- | ------------------- | -------------------------------------------------------- |\n| Pandora | HITL | `escalate`          | Long-lived. Talks to you. Routes the chain.              |\n| Envy    | AFK  | `intake`, `clarify` | Classifies external signals and clarifies requirements.  |\n| Toil    | AFK  | `triage`            | Decomposes incoming work; routes to design or execute.   |\n| Greed   | HITL | `design`, `review`  | Produces design briefs and explicitly requested reviews. |\n| War     | AFK  | `execute`           | Runs in a repo/worktree and changes code.                |\n\n**Built with**\n\n- [tmux](https://github.com/tmux/tmux) — HITL session host\n- [Claude Code](https://docs.claude.com/claude-code) and [Pi](https://pi.dev/) — harness runtimes\n\n## Getting Started\n\n### Prerequisites\n\n- Node `24.15.0` (pinned via Volta in root `package.json`)\n- `pnpm` v10+\n- macOS or Linux, Git\n- `tmux` and `claude` (Claude Code CLI) or `pi` on PATH\n\n### Installation\n\n```sh\ngit clone https://github.com/codethread/pandoras-box.git\ncd pandoras-box\npnpm install\npnpm run build\n```\n\n`pnpm run build` links the public `pithos`, `pdx`, and `pandora-spawn` bins onto your global PATH. The private test-only `fagent` bin is built for repo-local integration use but is not globally linked.\n\nIf `pnpm`'s global link doesn't work on your setup (Nix, restricted PATH,\netc.), use the Makefile to symlink the bins into `~/.local/bin` directly:\n\n```sh\nmake local\n```\n\nRequires `~/.local/bin` to be on your `PATH`.\n\n### Configuration\n\nRepo defaults live in [`./resources/`](./resources/) and are documented in\n[`./resources/README.md`](./resources/README.md).\n\nRun `pdx init` to create the data dir and seed the bundle-owned canonical\nconfig before Pandora starts:\n\n- `\u003cdata-dir\u003e/agents.toml`\n- `\u003cdata-dir\u003e/templates/`\n- `\u003cdata-dir\u003e/AGENTS.md`\n\n`pdx init` and `pdx open` always re-seed those bundle-owned files from repo\ndefaults.\n\nUser customisation lives in `\u003cuser-data-dir\u003e/`, where `\u003cuser-data-dir\u003e` is\n`$PDX_USER_DATA_DIR` or defaults to `\u003cdata-dir\u003e/config`. That directory keeps a\nscaffold-once `AGENTS.md`, `CLAUDE.md`, `artifacts.toml`, `supervisor.toml`, and `agents.toml`\nplus a re-seeded `PANDORA.md` reference so you can `cd` into it and ask a\ndirect harness session to edit config safely.\n\nTypical files:\n\n- `\u003cuser-data-dir\u003e/AGENTS.md` — tiny user-owned pointer to `PANDORA.md`\n- `\u003cuser-data-dir\u003e/CLAUDE.md` — same pointer for Claude direct sessions\n- `\u003cuser-data-dir\u003e/agents.toml` — scaffolded user-wide policy registry and Harness partial\n- `\u003cuser-data-dir\u003e/artifacts.toml` — user-owned Artifact Contracts scaffold (commented guidance only)\n- `\u003cuser-data-dir\u003e/supervisor.toml` — user-owned pdx launch policy scaffold; set `enforce_repo_root_trunk = false` under `[launch_preconditions]` here to disable the repo Scope default-branch guard\n- `\u003cuser-data-dir\u003e/PANDORA.md` — installed config reference, overwritten on `pdx init` / `pdx open`\n\nCustomize behavior with named policy packs declared in\n`\u003cuser-data-dir\u003e/agents.toml` and stored in user-owned `policies/*.md` files.\nUse `policy.add` / `policy.remove`, Agent-specific policy selection, and ordered\nmatch rules for project-specific behavior. User config must choose Harness launch\nsettings for Agents before they can launch. Supervisor launch preconditions live\nin `\u003cuser-data-dir\u003e/supervisor.toml`, not Agent prompt policy packs: by default,\npdx blocks repo Scope launches when the repository root is not on its remote\ndefault branch and creates a `launch_precondition` Repair Alert for Pandora to\nresolve/replay. External producers can feed Envy by writing intake events to\n`\u003cdata-dir\u003e/intake.sock` while `pdx open` is running.\n\nYou can also ask an agent to reconfigure Pandora's Box for you:\n\n```sh\npdx init\ncd ~/.pdx/config\nclaude\n# or your preferred harness\n```\n\nUse `PANDORA.md` in that user config directory as the main guide; `AGENTS.md`\nis only the tiny direct-agent pointer. Validate changes with\n`pandora-spawn preview`.\n\nUseful reset modes:\n\nArtifact status/rejection is an alpha schema break. If an existing DB fails with an incompatible `artifacts` schema error, reset runtime state with `pdx init --clean` / `pdx open --clean`; standalone Pithos users can run `pithos init --fresh`.\n\n- `pdx init` or `pdx open` — re-seed `\u003cdata-dir\u003e/agents.toml`, `\u003cdata-dir\u003e/templates/`, `\u003cdata-dir\u003e/AGENTS.md`, and `\u003cuser-data-dir\u003e/PANDORA.md`; scaffold missing `\u003cuser-data-dir\u003e/AGENTS.md`, `\u003cuser-data-dir\u003e/CLAUDE.md`, `\u003cuser-data-dir\u003e/agents.toml`, `\u003cuser-data-dir\u003e/artifacts.toml`, and `\u003cuser-data-dir\u003e/supervisor.toml`; keep user config, DB, runs, and logs\n- `pdx init --clean` or `pdx open --clean` — wipe runtime state only (DB, runs, logs); keep bundle-owned config and user config\n- `pdx init --nuke` or `pdx open --nuke` — wipe pdx-owned runtime/bundled state, preserve `\u003cuser-data-dir\u003e`, then reseed fresh canonical config\n\n### Uninstall\n\nThe supervisor writes its data directory to `~/.pdx`. Remove the bins and\nthat directory:\n\n```sh\nrm -rf ~/.pdx\n# if installed via pnpm:\npnpm -r unlink\n# if installed via `make local`:\nrm ~/.local/bin/{pithos,pdx,pandora-spawn}\n```\n\n## Usage\n\nTwo commands:\n\n```sh\npdx init    # create editable config without starting Pandora\npdx open    # release the Evils\npdx close   # back in the jar\n```\n\nFirst time meeting her, get the lay of the land:\n\n- _\"Tell me about yourself.\"_\n- _\"Tell me about scopes, tasks and chains.\"_\n- _\"How do we get work done around here?\"_\n\nThen put work into the queue through her:\n\n- _\"Create a design task in the frontend repo to figure out a WebSocket\n  implementation.\"_\n- _\"Build out a spec with Greed for our new persistence layer, then queue a\n  task for Toil to break it down and delegate execution in a worktree of the\n  backend repo.\"_\n\nEvery conversation deposits durable context — scopes, tasks, artifacts,\nchain edges — that survives runs. Old work stays queryable, so the next\ndelegation needs less re-explaining. Pandora gets sharper as you go.\n\nReviews are explicit work, not automatic gates: ask Pandora or Toil to queue a\n`review` task when you want Greed to walk through scoped work with you.\n\nWhen something goes sideways, she also drives the cleanup:\n\n- _\"Go kill Greed, she's chasing the wrong plan.\"_\n- _\"Toil's stuck — interrupt her and re-triage.\"_\n\n**Repair after interruption**: killing an Evil mid-task interrupts the Run,\nmarks the Held task failed, and creates a Repair Alert. Pandora repairs the\nBroken chain; pdx never resurrects a dead Agent as the same Run.\n\nIf Pandora herself is wedged, `pdx --help` lists the raw escape hatches.\n\n## Validation and integration tests\n\nFast local validation stays outside containers:\n\n```sh\npnpm test\npnpm run build\n```\n\n`pnpm test` runs the Vitest unit/package suites; it does not require real Harness credentials, Podman, or host tmux state. Use `pnpm lint` and `pnpm typecheck` for focused preflight checks.\n\nPodman-backed integration commands exercise container-local tmux and isolated pdx/Pithos data dirs without touching the host tmux server. They require Podman:\n\n```sh\npnpm run test:integration:tmux\npnpm run test:integration:pdx-open-fagent\n```\n\n`test:integration:tmux` builds `containers/Containerfile.integration`, mounts the current working tree into the container, sets isolated `PDX_DATA_DIR`, `PDX_USER_DATA_DIR`, `PITHOS_DB`, and `TMUX_TMPDIR`, then proves tmux can create, list, and kill a session through a container-local socket.\n\n`test:integration:pdx-open-fagent` copies the repo into the container, builds repo-local bins, configures Pandora/Toil/War with explicit `/workspace/packages/fagent/bin/fagent` argv paths, then drives `pdx open` through Toil triage, War failure, Pandora replay in the original `pdx--pandora` tmux pane, War completion, and `pdx close`. `tmux respawn-pane` is not an acceptable shortcut for this MVP path. `fagent` is test-only; normal user config should use Claude or Pi.\n\nOn failure, the script prints `pdx open fagent integration artifacts preserved at \u003cdir\u003e`. Inspect `\u003cdir\u003e/data/pdx.jsonl`, `\u003cdir\u003e/data/fagent-events.jsonl`, `\u003cdir\u003e/data/runs/*.stdout.log`, `\u003cdir\u003e/data/runs/*.stderr.log`, and `\u003cdir\u003e/user-config/`.\n\n`pnpm verify` runs the full gate in this order: lint, typecheck, unit tests, workspace build, `test:integration:tmux`, then `test:integration:pdx-open-fagent`.\n\n## Roadmap\n\nPre-v1; expect breaking changes.\n\n- [ ] First-class recipes — named, repeatable workflows the Evils follow for common shapes of work\n- [ ] Promote/demote an Evil between AFK and HITL mid-session\n- [ ] Interactive pickers for kill/show/transcript so you don't copy ids by hand\n- [ ] Pluggable control-plane backends — swap tmux for Zellij, remote SSH, etc. (the architecture is already decoupled)\n- [ ] Broader control-plane integration scenarios — extend the Podman/fagent flow beyond the current triage, execute-failure, Repair Alert replay, and completion path\n\nSee [open issues](https://github.com/codethread/pandoras-box/issues).\n\n## Contributing\n\nSee [`CONTRIBUTING.md`](./CONTRIBUTING.md), plus:\n\n- `UBIQUITOUS_LANGUAGE.md` — shared domain terms.\n- `AGENTS.md` — engineering rules for coding agents working on this repo.\n- `specs/README.md` — design specs index.\n- `packages/*/README.md` — per-package docs.\n\n## Licence\n\nMIT — see [`LICENCE`](./LICENCE).\n\n## Acknowledgements\n\n\u003e [...] after a while I realized I just wanted someone to talk to, while the system was working. And perhaps, as occasion might demand, someone to yell at.\n\u003e\n\u003e — Steve Yegge: [Gas Town: from Clown Show to v1.0](https://steve-yegge.medium.com/gas-town-from-clown-show-to-v1-0-c239d9a407ec)\n\n- The Effect community for the patterns this codebase leans on.\n- All the AI researchers building amazing LLMs.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodethread%2Fpandoras-box","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodethread%2Fpandoras-box","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodethread%2Fpandoras-box/lists"}