{"id":46447667,"url":"https://github.com/lespaceman/athena-flow-cli","last_synced_at":"2026-04-26T22:00:55.083Z","repository":{"id":341161669,"uuid":"1141513601","full_name":"lespaceman/athena-flow-cli","owner":"lespaceman","description":"An agentic workflow runtime","archived":false,"fork":false,"pushed_at":"2026-04-20T11:42:01.000Z","size":6417,"stargazers_count":20,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-20T12:33:27.253Z","etag":null,"topics":["ai","ai-agents","automation","claude-code","codex","llm","workflow","workflow-automation"],"latest_commit_sha":null,"homepage":"htttps://athenaflow.in","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/lespaceman.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"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":null,"dco":null,"cla":null}},"created_at":"2026-01-25T00:29:31.000Z","updated_at":"2026-04-20T11:39:59.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/lespaceman/athena-flow-cli","commit_stats":null,"previous_names":["lespaceman/athena-flow"],"tags_count":30,"template":false,"template_full_name":null,"purl":"pkg:github/lespaceman/athena-flow-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lespaceman%2Fathena-flow-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lespaceman%2Fathena-flow-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lespaceman%2Fathena-flow-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lespaceman%2Fathena-flow-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lespaceman","download_url":"https://codeload.github.com/lespaceman/athena-flow-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lespaceman%2Fathena-flow-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32314116,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T21:09:39.134Z","status":"ssl_error","status_checked_at":"2026-04-26T21:09:21.240Z","response_time":129,"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":["ai","ai-agents","automation","claude-code","codex","llm","workflow","workflow-automation"],"created_at":"2026-03-05T23:52:40.782Z","updated_at":"2026-04-26T22:00:55.062Z","avatar_url":"https://github.com/lespaceman.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Athenaflow CLI\n\n[![npm version](https://img.shields.io/npm/v/@athenaflow/cli)](https://www.npmjs.com/package/@athenaflow/cli)\n[![license](https://img.shields.io/npm/l/@athenaflow/cli)](https://github.com/lespaceman/athena-flow-cli/blob/main/LICENSE)\n[![CI](https://github.com/lespaceman/athena-flow-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/lespaceman/athena-flow-cli/actions/workflows/ci.yml)\n[![node](https://img.shields.io/node/v/@athenaflow/cli)](https://nodejs.org)\n\n**Deterministic orchestration for non-deterministic agents.**\n\nAI coding agents are getting better at reasoning -- but long-horizon tasks still break. Prompts drift, results vary between runs, and there's no good way to package what worked into something your whole team can reuse. The agent isn't the bottleneck anymore. The harness is.\n\nAthenaflow is a **workflow runtime** for [Claude Code](https://claude.com/product/claude-code) and [OpenAI Codex](https://chatgpt.com/codex). It adds structured workflows, real-time observability, session persistence, and a plugin system -- so agent-driven tasks produce consistent results across runs, teams, and models.\n\n```\nnpm install -g @athenaflow/cli \u0026\u0026 athena\n```\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/demo.gif\" alt=\"Athenaflow terminal UI\" width=\"960\" /\u003e\n\u003c/p\u003e\n\n\u003e **[Read the docs](https://athenaflow.in/docs)** -- guides, workflow authoring, plugin API, and more.\n\n\u003cbr\u003e\n\n## Why Athenaflow?\n\nCoding agents work well for one-off tasks. The moment you need **repeatable, multi-step execution** -- e2e test generation, migration plans, release workflows -- things fall apart:\n\n| Pain point                  | What goes wrong                                                   |\n| --------------------------- | ----------------------------------------------------------------- |\n| **No reproducibility**      | Same prompt, same model, different output every time              |\n| **Long-horizon drift**      | Without checkpoints, agents compound small mistakes into big ones |\n| **Prompts aren't portable** | What one developer got working doesn't transfer to the team       |\n| **Black-box execution**     | You see the final output, not the 40 tool calls that got there    |\n| **CI as an afterthought**   | Most harnesses are built for interactive use, not pipelines       |\n\nAthenaflow introduces a **workflow layer** between you and the underlying harness.\nWorkflows are declarative, versioned, and shareable -- they define prompt templates,\nmulti-session loops with completion tracking, plugin bundles, isolation policies,\nand model preferences. The runtime handles the rest.\n\n**Workflows encode what works** -- not just a prompt, but the loop logic, progress tracking, and tool config that make it reliable. Define once, run anywhere.\n\n**A marketplace for agent workflows** -- browse, install, and update community-built workflows like packages.\n\n**Real-time observability** -- a live terminal feed of every tool call, permission decision, and result as it happens.\n\n**Sessions persist and resume** -- every run is saved to SQLite. Pick up where you left off with full state.\n\n**Harness-agnostic** -- same workflows, same UI, same session model across Claude Code and Codex.\n\n**CI-native** -- `athena exec` runs headlessly with safe defaults, JSONL output, and structured exit codes.\n\n\u003cbr\u003e\n\n## Get Started\n\n**1. Install** -- requires Node.js 20+ and at least one harness (`claude` or `codex`) on your PATH.\n\n```bash\nnpm install -g @athenaflow/cli\n```\n\n**2. Run** -- the setup wizard handles theme, harness verification, and your first workflow.\n\n```bash\nathena\n```\n\n**3. Explore**\n\n```bash\nathena resume                              # Pick up where you left off\nathena sessions                            # Browse past sessions\nathena workflow install e2e-test-builder   # Install a workflow from the marketplace\n```\n\n\u003e **[Full walkthrough](https://athenaflow.in/docs)**\n\n\u003cbr\u003e\n\n## Harnesses\n\n| Harness                                   | Status    | Integration                                    |\n| ----------------------------------------- | --------- | ---------------------------------------------- |\n| Claude Code                               | Supported | Hook events forwarded over a local Unix socket |\n| [OpenAI Codex](https://chatgpt.com/codex) | Supported | Integrated via `codex app-server` protocol     |\n| opencode                                  | Planned   | Adapter placeholder; not yet enabled           |\n\n\u003cbr\u003e\n\n## Workflows\n\nWorkflows package prompt templates, loop strategies, plugin dependencies, isolation policies, and model config into a single portable unit. Anyone can author and share them.\n\n```bash\nathena workflow list                        # See what's installed\nathena workflow search                      # Browse available workflows\nathena workflow install e2e-test-builder    # Install from the marketplace\nathena workflow use e2e-test-builder        # Set as the active workflow\nathena workflow upgrade                     # Re-sync all from source\n```\n\nManage marketplace sources:\n\n```bash\nathena marketplace add owner/repo           # Add a marketplace source\nathena marketplace add ./local/path         # Add a local marketplace\nathena marketplace list                     # List configured sources\nathena marketplace remove owner/repo        # Remove a source\n```\n\nInstall from a local file or a specific marketplace ref:\n\n```bash\nathena workflow install ./path/to/workflow.json\nathena workflow install e2e-test-builder@lespaceman/athena-workflow-marketplace\n```\n\n\u003e **[Author your own workflows](https://athenaflow.in/docs)**\n\n\u003cbr\u003e\n\n## CI / Automation\n\n`athena exec` is built for pipelines. Safe by default -- permission and question hooks fail unless you opt in.\n\n```bash\nathena exec \"summarize risk in this PR\"                                        # plain text\nathena exec \"run checks\" --json --on-permission=deny --on-question=empty       # JSONL\nathena exec \"write release notes\" --output-last-message release-notes.md       # artifact\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eGitHub Actions\u003c/summary\u003e\n\n```yaml\nname: athena-exec\non: [pull_request]\njobs:\n  athena:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: actions/setup-node@v4\n        with:\n          node-version: 20\n      - run: npm ci\n      - run: npx @athenaflow/cli exec \"summarize risk in this PR\" \\\n          --json --on-permission=deny --on-question=empty \\\n          --output-last-message athena-summary.md\n      - uses: actions/upload-artifact@v4\n        with:\n          name: athena-summary\n          path: athena-summary.md\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eGitLab CI\u003c/summary\u003e\n\n```yaml\nathena_exec:\n  image: node:20\n  script:\n    - npm ci\n    - npx @athenaflow/cli exec \"summarize pipeline status\" \\\n      --json --on-permission=deny --on-question=empty \\\n      --output-last-message athena-summary.md\n  artifacts:\n    paths:\n      - athena-summary.md\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eExit codes\u003c/summary\u003e\n\n| Code | Meaning                           |\n| ---- | --------------------------------- |\n| `0`  | Success                           |\n| `2`  | Usage / validation error          |\n| `3`  | Bootstrap / configuration failure |\n| `4`  | Runtime / process failure         |\n| `5`  | Non-interactive policy failure    |\n| `6`  | Timeout exceeded                  |\n| `7`  | Output write failure              |\n\n\u003c/details\u003e\n\n\u003cbr\u003e\n\n## Configuration\n\nConfig merges in order: **global \u0026rarr; project \u0026rarr; CLI flags**.\n\n```\n~/.config/athena/config.json        # Global defaults\n{projectDir}/.athena/config.json    # Project overrides\n```\n\n```json\n{\n\t\"harness\": \"claude-code\",\n\t\"model\": \"sonnet\",\n\t\"plugins\": [\"/path/to/plugin\"],\n\t\"activeWorkflow\": \"e2e-test-builder\"\n}\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eCLI flags\u003c/summary\u003e\n\n| Flag            | Description                                   |\n| --------------- | --------------------------------------------- |\n| `--project-dir` | Project directory (default: cwd)              |\n| `--plugin`      | Path to a plugin directory (repeatable)       |\n| `--isolation`   | `strict` (default) · `minimal` · `permissive` |\n| `--theme`       | `dark` (default) · `light` · `high-contrast`  |\n| `--ascii`       | ASCII-only UI glyphs                          |\n| `--verbose`     | Extra rendering detail                        |\n\n**exec-only:**\n\n| Flag                    | Description                                            |\n| ----------------------- | ------------------------------------------------------ |\n| `--continue`            | Resume most recent exec session (or `--continue=\u003cid\u003e`) |\n| `--json`                | JSONL lifecycle events on stdout                       |\n| `--output-last-message` | Write final assistant message to a file                |\n| `--ephemeral`           | Disable session persistence for this run               |\n| `--on-permission`       | `allow` · `deny` · `fail` (default)                    |\n| `--on-question`         | `empty` · `fail` (default)                             |\n| `--timeout-ms`          | Hard timeout for the run                               |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eCommands\u003c/summary\u003e\n\n| Command             | Description                                                  |\n| ------------------- | ------------------------------------------------------------ |\n| _(default)_         | Start interactive session in cwd                             |\n| `setup`             | Re-run setup wizard                                          |\n| `sessions`          | Interactive session picker                                   |\n| `resume [id]`       | Resume most recent or specific session                       |\n| `exec \"\u003cprompt\u003e\"`   | Headless run for CI / scripting                              |\n| `workflow \u003csub\u003e`    | `install` · `list` · `search` · `remove` · `upgrade` · `use` |\n| `marketplace \u003csub\u003e` | `add` · `remove` · `list`                                    |\n\n\u003c/details\u003e\n\n\u003cbr\u003e\n\n## Development\n\n```bash\nnpm install \u0026\u0026 npm run build    # Build\nnpm test                        # Test\nnpm run typecheck               # Type-check\nnpm run lint                    # Lint\nnpm run dev                     # Watch mode\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eCodex protocol bindings\u003c/summary\u003e\n\nFiles in `src/harnesses/codex/protocol/generated` are auto-generated from the `codex app-server` schema -- do not edit by hand. Refresh with:\n\n```bash\nscripts/update-codex-protocol-snapshot.mjs\n```\n\nCommit the output so others can build without the generator.\n\n\u003c/details\u003e\n\n\u003cbr\u003e\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flespaceman%2Fathena-flow-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flespaceman%2Fathena-flow-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flespaceman%2Fathena-flow-cli/lists"}