Skip to content
znationPublic

About

An agentic software team.

Resources

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

9,705 Commits

Folders and files

Repository files navigation

tumwater

Getting Started

npm install -g tumwater
cd your-project
tumwater init "Build a tiny markdown-to-html converter CLI in Python."
tumwater start --gui

Then open http://127.0.0.1:7180 to watch the team work. Requires Node 20.3+ on macOS or Linux.

The tumwater web dashboard running tumwater's own team: a sidebar with the project, its team status, and the Team, History, Usage, Failures, and Settings views, with today's spend against the cap and the pause control; the director prompt box; and today's progress (roles running, commits merged, runs, open backlog) above the roles grouped by what they are doing, each with its status, current work or last result, spend, and controls

⚠️ Warning: tumwater eats tokens

tumwater runs models continuously, all day, on every role. A busy team can burn through on the order of a billion tokens a day or more. On pay-per-token API keys that is real, unbounded money; on subscription backends it burns through your plan's usage windows just as fast. Set maxDailyCostUsd before you start, and watch actual spend with tumwater report and tumwater status.

tumwater is an opinionated autonomous development team running on a pluggable agent backend — pi is the default, and Claude Code, OpenCode and Codex are selectable with backend. You write a short project brief, and a team of roles (feature, bugfix, planning, tests, cleanup, docs, and more) builds the project one small, reviewed commit at a time. It came from wanting to write only the brief and let a team of always-on specialists do the rest: each role owns one concern, merges one change per run, sleeps when it has nothing to do, and wakes when main moves. All project state lives in the local git repo, and no remote is ever touched. The words used here (team, role, run, merge) are defined in docs/glossary.md.

Install

Requires Node 20.3 or later on macOS or Linux.

npm install -g tumwater

Or run any command without installing: npx tumwater. To run from a checkout of this repo instead: npm install && npm run build && npm link.

With claude installed and logged in, npm run smoke:claude is an opt-in live check of the claude backend: it drives the real CLI through a throwaway repo (a few cents of API-equivalent spend on a subscription) and is not part of npm test, which stays green without claude. npm run smoke:opencode is the same live check for the opencode backend, driving the real opencode CLI against its free DeepSeek tier; it needs an OpenCode V2 install (brew install opencode) and is also outside npm test. npm run smoke:codex is the same live check for the codex backend, driving the real codex CLI against a logged-in ChatGPT subscription; it needs a Codex install and is also outside npm test.

Status

v0.8.3: working tumwater. The director and 15 of the 17 roles are enabled by default; selfcheck, which files tumwater bugs from tumwater's own event log, and feedback, which files them as GitHub issues on znation/tumwater, are opt-in (roles.selfcheck.enabled, roles.feedback.enabled).

Open work: PLANS.md (planned), BUGS.md (open bugs), QUESTIONS.md (open questions).

Usage

cd your-project                 # a new or existing directory
tumwater init "Build a tiny markdown-to-html converter CLI in Python."
                                # --template, --file, and --adopt pick a starting point (see docs/cli.md)
tumwater start                  # start the team (Ctrl+C to stop)
tumwater start --gui            # ... and serve the browser dashboard at http://127.0.0.1:7180
tumwater start --tui            # ... and attach the terminal TUI in the same window
tumwater start --for 2h         # run for a bounded window, then finish current work, summarize, and exit
tumwater start --once           # one round of runs for cron/CI; exits 3 if a run failed

A fresh or empty project is seeded with "bootstrap": {"untilPlansDone": 5}, which holds the maintenance roles until 5 plans are done; remove it from tumwater.json to end that early.

From another terminal, tumwater tui or the browser dashboard watches the team, tumwater status and tumwater logs -f check it, tumwater brief --file <path> replaces the brief, tumwater prompt "<text>" sends a message to the director's inbox, tumwater plan and tumwater bug file backlog entries, tumwater land puts your own hand-made commit on main under the team's merge lock, tumwater revert <sha> undoes one merged change on main, and tumwater pause, resume, wake, and stop control the roles. tumwater doctor audits the team and tumwater report shows usage and cost. gui --all-interfaces exposes the dashboard, and with it the director prompt, to your whole network, so pair it with --token <secret>.

tumwater prompt --attach <image> gives a role an image to read at its next run. When a role's model cannot read images, the command refuses the attachment up front (naming the fix) unless the role reroutes a blind read to a vision model, in which case it says where the message will run; the dashboards and tumwater role <id> say which roles read images and where a blind run reroutes.

Every command, flag, and TUI key is in docs/cli.md; tumwater help prints the same list, and tumwater completion bash|zsh|fish prints shell completion. Settings live in tumwater.json and edits apply live while the team runs; see docs/config.md.

Backends: any OpenAI-compatible model pi can reach works, chosen by model in tumwater.json with a fallback that a failing role switches to. backend beside model picks who runs it: "backend": "claude" runs a model id on Claude Code, "backend": "opencode" on the OpenCode CLI — its free DeepSeek tier needs no login or API key — and "backend": "codex" on the Codex CLI's ChatGPT subscription (no API key; its two usage windows behave like a claude subscription's). Requirements, the fallback, free-ness, and usage-window behavior, and how subscription runs are billed (as estimated spend, outside the daily cap) are in docs/backends.md.

Default models by backend: when a tier or job resolves no model, the backend's own tier defaults fill in (an explicit model always wins over them; a tier left out of a model map first inherits default):

backend small default strong
pi its saved default its saved default (pi default in tumwater status) its saved default
claude claude-haiku-5-5 claude-haiku-5-5 claude-opus-5-5
opencode its own default its own default its own default
codex gpt-6-luna gpt-6-luna gpt-6.1-sol

pi and OpenCode carry no tier defaults of their own, so their own saved/default model applies when a job names no model; the others resolve the concrete model shown. The director runs the strong tier, so with no model configured it is claude-opus-5-5 on claude and gpt-6.1-sol on codex.

Mixing providers: model says which model, backend says which program runs it (pi, the default, claude, opencode or codex). A tier entry, a role, a review and a fallback step each take an object with both, so one config can mix a Claude strong tier with pi providers:

{
  "model": {
    "default": "huggingface/deepseek-ai/DeepSeek-V4.1-Flash:deepinfra",
    "strong": { "backend": "claude", "model": "claude-opus-5-5" }
  },
  "fallback": "omlx/Qwen3.8-27B-MLX-oQ4e-mtp"
}

The default tier runs on pi through Hugging Face, the strong model jobs (the director, the plan role, the reviewer, and the conflict resolver) run on the claude CLI's included usage, and the fallback runs on pi through oMLX — all concurrently, under the team's maxConcurrent cap. An OpenCode tier is { "backend": "opencode", "model": "deepseek-v4.1-flash-free" }, so its free tier can sit beside pi and claude in one config; a codex tier is { "backend": "codex", "model": "gpt-6.1-sol" }, so a ChatGPT subscription can cover the team's default tier beside pi and claude. A Claude model that should stay on pi (billed per token) is the plain anthropic/claude-… selector. See plans/agent-backends.md §3.

For how the roles, review gate, scheduling, and updates work, see docs/how-it-works.md. For a measured comparison of tumwater's own code against human-written open source, see docs/code-metrics.md.

Appendix: the brief

The brief this repository was started from, amended 2026-11-16 where the original vision proved impractical. tumwater still reads the brief from between the markers below on every run.

Idea: agentic harness

Opinionated. Built on pi. Lots of autonomous loops. You write the markdown/initial prompt, then steer: you, usually through your own interactive agent on a strong model, write and sharpen the entries in PLANS.md and BUGS.md, and the loops build them. (Amended 2026-11-16: the original "you only write the initial prompt" proved impractical; steering through the backlog is the intended use.) It builds the project with immense effort. First puts the initial prompt and project status into README.md. Background loops are observable by gui/tui/log. GUI/TUI also gives user a main prompt. Loop sleeps a while when the prompt results in no further changes. Starts again after a while to see if the answer has changed due to the new state of the world. Each run attempts to find something to do, do one thing, commit, merge to main. The find-something-to-do part is role specific. Each loop has a role:

  • Make the code more organized
  • Increase unit test code coverage
  • Make the code cleaner
  • Make the code less repetitive
  • Implement a planned feature (tracked in PLANS.md)
  • Fix a bug (tracked in BUGS.md in repo)
  • Plan a feature (write markdown plan, add to PLANS.md)
  • Keep the README up to date
  • Make an improvement to the code

Assumptions: run within a git repo dir. Each loop uses a persistent git workspace and branch. Each loop keeps itself synced up with git main. Don't involve git remotes at all; do everything locally and keep all project state within the git repo.

About

An agentic software team.

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages