{
  "markdown": "> 🌐 **English** · [日本語](README.ja.md)\n\n# totsuka\n\n**AI-driven dev-flow automation.** totsuka detects task instructions from your\ntask sources (GitHub Issues, Notion, Slack mentions), matches them to\nworkflows, and orchestrates them to AI coding agents (herdr, orca) — each in\nits own git worktree — then publishes the result as a pull request or writes\nit back to the source.\n\n- **Task sources**: GitHub Issues / Projects, Notion databases, Slack mentions\n  (drafts replied under your own name after your approval)\n- **Agents**: [herdr](https://herdr.dev/) and [orca](https://www.onorca.dev/)\n  — third-party agent IDEs, each driven over totsuka's plugin protocol\n- **Isolation**: one task = one repo = one worktree = one branch\n- **Output policies**: open a pull request, write back to the source, or none\n- **Local-first**: a single CLI binary, no daemon, secrets stay in your own\n  secret store (1Password, Keychain, env, or a command)\n\n> Status: pre-1.0, targeting the v1 scope — see the\n> [releases page](https://github.com/tomoya-k31/totsuka/releases) for the\n> current version. macOS only for now; the code is XDG-compliant and\n> platform boundaries are abstracted for a future Linux port.\n\n## Prerequisites\n\ntotsuka orchestrates agents; it does not bundle one. Install at least one\nagent IDE and point a workflow at it:\n\n- **[herdr](https://herdr.dev/)** — **0.7.5 or newer is required**. The plugin\n  reads herdr's own version from `ping` during `initialize` and refuses\n  anything older with `CONFIG_INVALID`. There is no upper bound: a newer herdr\n  is never refused.\n- **[orca](https://www.onorca.dev/)** — driven through the `orca` CLI.\n\n## Install\n\n### Homebrew\n\n```sh\nbrew install tomoya-k31/tap/totsuka\n```\n\nThat is the whole install: no `sudo`, no tree to place by hand, and no\nquarantine attribute to clear. Homebrew fetches the release tarball with plain\n`curl`, which does not set `com.apple.quarantine` — measured on macOS 15.7.3,\non the binary and on the bundled plugins.\n\nHomebrew requires trust for third-party taps.\n**Naming the formula grants it in the same command**: the install prints one\nline — `==> Trusted formula tomoya-k31/tap/totsuka` — and carries on. There is\nno prompt to answer.\n\nUpgrade with `brew upgrade totsuka`; the release workflow points the formula at\neach new release.\n\n### Prebuilt tarball (GitHub Releases)\n\nFor a machine without Homebrew. Download the macOS universal tarball from the\n[latest release](https://github.com/tomoya-k31/totsuka/releases/latest). It\ncontains `totsuka` **and the bundled plugins**, so keep the tree together and\nsymlink the binary onto your `PATH`:\n\n```sh\ntar -xzf totsuka-*-macos-universal.tar.gz\nsudo rm -rf /usr/local/lib/totsuka\nsudo mv totsuka-*-macos-universal /usr/local/lib/totsuka\nsudo ln -sf /usr/local/lib/totsuka/totsuka /usr/local/bin/totsuka\n```\n\nThe whole directory moves, not just the binary: `totsuka` looks for the bundled\nplugins next to itself, which is how `totsuka setup` installs them with no path\nfrom you. Keeping the tree in place also means adding or reinstalling a plugin\nlater needs no second download.\n\nEverything is ad-hoc–signed. If Gatekeeper blocks it, clear the quarantine\nattribute on the whole tree once:\n\n```sh\nsudo xattr -dr com.apple.quarantine /usr/local/lib/totsuka\n```\n\n### From source\n\n```sh\ncargo install --git https://github.com/tomoya-k31/totsuka orchestrator-cli\n```\n\nThis installs the CLI only. Plugins are built from a checkout — see\n[the plugin development guide](docs/plugin-dev-guide.md).\n\n## Quickstart (5 minutes, 1 task)\n\n```sh\n# 1. Answer a few questions. Pick a starting recipe, name your repositories,\n#    say where your secrets live — the wizard writes the config, installs and\n#    enables the plugins the recipe needs, and finishes by running `doctor`.\ntotsuka setup\n\n# 2. Register the secrets it listed. It never handles the values itself, so it\n#    prints one ready-to-paste command per secret, e.g.\nsecurity add-generic-password -U -s totsuka -a github-token -w '<the token>'\n\n# 3. Run one cycle (add --watch to keep polling).\ntotsuka run --dry-run   # preview: which task -> which repo -> which agent\ntotsuka run             # execute: fetch -> dispatch -> monitor -> publish\n```\n\n`setup` exits with code 3 until every secret it listed exists — that is\n`doctor` reporting real work left to do, not a failure of the setup itself.\n\n**`doctor` stays red until after your first `totsuka run`**, even with every\nsecret registered: the `state-db` check fails while the state database does not\nexist, and only `run` creates it. So the order above is the order that goes\ngreen — register the secrets, run once, then `totsuka doctor` exits 0. It may\nstill print `warn:` lines (an unset hook token, no bundled plugins); those are\nadvisory and do not fail it.\n\nInspect progress with `totsuka status`, drill into a task with\n`totsuka task show <id>`, and follow logs with `totsuka logs -f`.\n\n`totsuka init` is still there for CI and scripted bootstraps: it never prompts,\nand writes only directories plus a fully commented config skeleton. `setup`\nfills that skeleton in, so running `init` first is harmless but unnecessary.\n\n`setup` also has a non-interactive form: answer once, keep the file, and bring\nthe next machine up from it. `setup` never writes a secret value into the file —\nit records which backend to use and prints the commands to register the values —\nso a file it generated is safe to commit to your dotfiles.\n\n```sh\ntotsuka setup --save-answers ~/dotfiles/totsuka-answers.toml\ntotsuka setup --answers ~/dotfiles/totsuka-answers.toml --yes   # on the next machine\n```\n\nNew machine, dev checkout, token rotation, and recovery are covered end to end\nin the [setup playbook](docs/setup-playbook.md).\n\n## Documentation\n\n- **What totsuka is**: [docs/orchestrator-spec.md](./docs/orchestrator-spec.md)\n- **Setup playbook**: [docs/setup-playbook.md](./docs/setup-playbook.md)\n- **Slack setup**: [docs/slack-setup.md](./docs/slack-setup.md)\n- **Configuration reference**: [docs/config-reference.md](./docs/config-reference.md)\n- **Operations guide** (doctor / worktree cleanup / FAQ): [docs/operations-guide.md](./docs/operations-guide.md)\n- **Plugin development guide**: [docs/plugin-dev-guide.md](./docs/plugin-dev-guide.md)\n- **Table of contents**: [docs/index.md](./docs/index.md) · **Changelog**: [CHANGELOG.md](./CHANGELOG.md)\n\nThose pages are generated from [`ai-docs/`](./ai-docs/), an\n[Open Knowledge Format (OKF) v0.2](https://raw.githubusercontent.com/GoogleCloudPlatform/knowledge-catalog/refs/heads/main/okf/SPEC.md)\nKnowledge Bundle holding the repository's full knowledge — design decisions,\nmeasurements, and history. Read that if you are working on totsuka itself.\n\n## Contributing\n\nConventional Commits are required (`type(scope): description`). Releases are cut\nby merging the [release-please](https://github.com/googleapis/release-please)\nRelease PR. Docs changes are validated by `bash scripts/okf-lint.sh ai-docs`.\n\n## License\n\n[MIT](./LICENSE).\n",
  "bytes": 7011,
  "sha": "5e21333c460ecf1d832823733cf837dc4c805f38ca81410dcc5ccadbc92956f3",
  "repo_slug": "tomoya-k31/totsuka",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_tomoya_k31_totsuka_ai_docs_index_md_5412ef9a/readme"
}