{"id":43793722,"url":"https://github.com/cephalization/math","last_synced_at":"2026-02-05T20:36:26.163Z","repository":{"id":331922771,"uuid":"1132261245","full_name":"cephalization/math","owner":"cephalization","description":"A light meta agent orchestration harness designed to coordinate multiple AI agents working together to accomplish tasks from a TODO list.","archived":false,"fork":false,"pushed_at":"2026-01-29T16:08:52.000Z","size":204,"stargazers_count":1,"open_issues_count":11,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-29T19:53:45.728Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cephalization.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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":null,"dco":null,"cla":null}},"created_at":"2026-01-11T16:25:57.000Z","updated_at":"2026-01-21T16:56:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cephalization/math","commit_stats":null,"previous_names":["cephalization/math"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/cephalization/math","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cephalization%2Fmath","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cephalization%2Fmath/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cephalization%2Fmath/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cephalization%2Fmath/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cephalization","download_url":"https://codeload.github.com/cephalization/math/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cephalization%2Fmath/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29133400,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-05T19:36:52.185Z","status":"ssl_error","status_checked_at":"2026-02-05T19:35:40.941Z","response_time":65,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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":[],"created_at":"2026-02-05T20:36:25.008Z","updated_at":"2026-02-05T20:36:26.021Z","avatar_url":"https://github.com/cephalization.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# math - Multi-Agent Task Harness\n\nA light meta agent orchestration harness designed to coordinate multiple AI agents working together to accomplish tasks managed by [dex](https://dex.rip).\n\n## Core Concept\n\nThe primary responsibility of this harness is to **reduce context bloat** by digesting a project plan into focused documents:\n\n| Document | Purpose |\n| ---------- | --------- |\n| `dex` | Task tracking with status, dependencies, and context |\n| `LEARNINGS.md` | Accumulated insights from completed tasks |\n| `PROMPT.md` | System prompt with guardrails (\"signs\") |\n\nThe harness consists of a simple for-loop, executing a new coding agent with a mandate from `PROMPT.md` to complete a *single* task from dex, while reading and recording any insight gained during the work into `LEARNINGS.md`.\n\n### Directory Structure\n\n| Path | Description |\n| ---- | ----------- |\n| `.dex/` | Dex task storage (tasks.jsonl) |\n| `.math/todo/` | Active sprint files (PROMPT.md, LEARNINGS.md) |\n| `.math/backups/` | Archived learnings from `math iterate` |\n\n## Requirements\n\n**[Bun](https://bun.sh) is required** to run this tool. Node.js is not supported.\n\n```bash\n# Install Bun (macOS, Linux, WSL)\ncurl -fsSL https://bun.sh/install | bash\n```\n\n**[dex](https://dex.rip) is required** for task management.\n\n```bash\n# Install dex\nbun add -g @zeeg/dex\n```\n\n**[OpenCode](https://opencode.ai) is required** to run the agent loop.\n\n```bash\n# Install OpenCode\ncurl -fsSL https://opencode.ai/install | bash\n```\n\n## Installation\n\n### From npm (recommended)\n\n```bash\n# Global install (recommended)\nbun install -g @cephalization/math\n\n# One-off usage \nbunx @cephalization/math \u003ccommand\u003e\n```\n\n### From source (for development)\n\n```bash\ngit clone https://github.com/cephalization/math.git\ncd math\nbun install\nbun link\n```\n\n## Usage\n\n### Initialize a project\n\n```bash\nmath init\n```\n\nInitializes dex and creates a `.math/todo/` directory with template files. Offers to run **planning mode** to help you break down your goal into tasks.\n\nOptions:\n\n- `--no-plan` - Skip the planning prompt\n- `--model \u003cmodel\u003e` - Model to use (default: `anthropic/claude-opus-4-5`)\n\n### Plan your tasks\n\n```bash\nmath plan\n```\n\nOptions:\n\n- `--model \u003cmodel\u003e` - Model to use (default: `anthropic/claude-opus-4-5`)\n- `--quick` - Skip clarifying questions and generate plan immediately\n\nInteractively plan your tasks with AI assistance. The planner uses a two-phase approach:\n\n1. **Clarification phase**: The AI analyzes your goal and asks 3-5 clarifying questions\n2. **Planning phase**: Using your answers, it creates tasks in dex with proper dependencies\n\nUse `--quick` to skip the clarification phase if you want a faster, assumption-based plan.\n\n### Run the agent loop\n\n```bash\nmath run\n```\n\nOptions:\n\n- `--model \u003cmodel\u003e` - Model to use (default: `anthropic/claude-opus-4-5`)\n- `--max-iterations \u003cn\u003e` - Safety limit (default: 100)\n- `--pause \u003cseconds\u003e` - Pause between iterations (default: 3)\n\nIteratively run the agent loop until all tasks are complete. Each iteration will:\n\n- Query dex to find the next ready task\n- Invoke the agent with `PROMPT.md` and task context\n- The agent will complete the task and mark it done in dex\n- The agent will log learnings to `LEARNINGS.md`\n- The agent will commit the changes to the repository\n- The agent will exit\n\n### Check status\n\n```bash\nmath status\n```\n\nShows task progress with a visual progress bar and next task info.\n\n### Start a new sprint\n\n```bash\nmath iterate\n```\n\nArchives completed tasks and resets for a new goal:\n\n- Completed dex tasks are archived\n- LEARNINGS.md is backed up and reset\n- PROMPT.md is preserved (keeping your accumulated \"signs\")\n- Offers to run planning mode for your new goal\n\nOptions:\n\n- `--no-plan` - Skip the planning prompt\n\n## Task Management\n\nTasks are managed by [dex](https://dex.rip). Common commands:\n\n```bash\n# List ready tasks\ndex list --ready\n\n# Create a new task\ndex create \"Task description\" --description \"Detailed context\"\n\n# View task details\ndex show \u003ctask-id\u003e\n\n# Mark task complete\ndex complete \u003ctask-id\u003e --result \"What was done\"\n\n# View overall status\ndex status\n```\n\nSee the [dex documentation](https://dex.rip/cli) for full CLI reference.\n\n## The Loop\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                      math run (loop)                        │\n│  ┌───────────────────────────────────────────────────────┐  │\n│  │  1. Query dex for ready tasks                         │  │\n│  │  2. If all complete → EXIT SUCCESS                    │  │\n│  │  3. Invoke agent with PROMPT.md + task context        │  │\n│  │  4. Agent: start task → implement → test → commit     │  │\n│  │  5. Agent: complete task in dex → log learnings       │  │\n│  │  6. Loop back to step 1                               │  │\n│  └───────────────────────────────────────────────────────┘  │\n└─────────────────────────────────────────────────────────────┘\n```\n\n## Planning Mode\n\nWhen you run `math init`, `math iterate`, or `math plan`, the harness can invoke [OpenCode](https://opencode.ai/docs/cli/) to help you plan:\n\n1. You describe your high-level goal\n2. OpenCode asks clarifying questions to understand your requirements\n3. You answer the questions interactively\n4. OpenCode breaks your goal into discrete, implementable tasks\n5. Tasks are created in dex with proper dependencies\n6. You're ready to run `math run`\n\nThis bridges the gap between \"I want to build X\" and a structured task list.\n\n## Signs (Guardrails)\n\n\"Signs\" are explicit guardrails in `PROMPT.md` that prevent common agent mistakes. Add new signs whenever you discover a failure mode:\n\n```markdown\n### SIGN: Descriptive Name\n\nClear explanation of what to do or avoid.\n\n❌ WRONG: Example of the mistake\n✅ RIGHT: Example of correct behavior\n```\n\nSigns accumulate over time, making the agent increasingly reliable.\n\n## Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `MODEL`  | `anthropic/claude-opus-4-5` | Model to use |\n\n## Credits\n\n- **Ralph Methodology**: [Geoffrey Huntley](https://ghuntley.com/ralph/)\n- **Task Management**: [dex](https://dex.rip)\n- **Agent Runtime**: [OpenCode](https://opencode.ai)\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcephalization%2Fmath","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcephalization%2Fmath","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcephalization%2Fmath/lists"}