Taskcell: a self-hosted software factory.
It takes tasks from GitHub, GitLab or Linear, builds them with AI agents in a sealed sandbox, and opens pull requests for a human to review.
Taskcell turns a well-written ticket into a reviewed pull request. You label an issue; Taskcell checks that the ticket is clear enough, writes a tech spec if needed, runs a coding agent inside a locked-down Docker container, has a second model review the change, runs your tests, and opens a PR. It runs on your own machine, a server, or GitHub Actions, with your own model subscription or API key. The agent is treated as untrusted: it never holds your repository token, and nothing it writes reaches your repository without passing host-side checks and a human review.
Naming.
vanguardis the old name oftaskcelland still works. The repository moved fromspietrza/vanguardtospietrza/taskcell(old links redirect). EveryVANGUARD_*environment variable has aTASKCELL_*name and the old name is still read (table: docs/environment-variables.md). Per-repo state now lives in.taskcell/; a repo that still has only.vanguard/keeps using it (with a deprecation warning) until you rename it. Migrating: add.taskcell/to.gitignore. Website: taskcell.dev.
Every task passes six stations:
- Card. A ticket on GitHub, GitLab or Linear gets a trigger label (
ready for specorready for agent) or moves to a trigger state. A deterministic triage check parks vague tickets atneeds infobefore any model is called. - Spec. For
ready for spec, a read-only planning pass researches the codebase and posts a<tech_spec>comment. No code is written. - Sealed cell. The agent implements the change in a Docker sandbox: non-root, capabilities dropped, no repository token, and optionally no network beyond an allowlist.
- Review. A second model, optionally from another provider, reviews the diff in a fresh context and fixes what it finds, then a simplify pass tidies the change.
- Gates. The host runs your verify command (Proof of Work), an optional conformance check against the spec, and a secret scan of the outgoing diff. A red gate sends the change back for up to two repair rounds.
- Pull request. The host pushes the branch and opens the PR, ready for review when every gate passed and a draft otherwise. A human reviews and merges.
Run it once per ticket with taskcell run, or let taskcell watch (or the GitHub Actions workflows) pick up labelled tickets on their own. Details: docs/autonomous-loop.md and docs/architecture.md.
You need Node 24+, pnpm, Docker and a Claude subscription token (claude setup-token) or an Anthropic API key.
git clone https://github.com/spietrza/taskcell && cd taskcell
pnpm install
pnpm build
pnpm link --global
docker/build.sh # builds taskcell-sandbox:latest (node + git + claude, codex and linear CLIs)Check the setup against your target repository, then run one issue:
export CLAUDE_CODE_OAUTH_TOKEN=... # or ANTHROPIC_API_KEY=...
taskcell doctor --source github --github-repo owner/repo
taskcell run --github owner/repo#123 --repo /path/to/repo --skills ./skills --llm-proxy--llm-proxy keeps the model credential in a sidecar and limits the sandbox's network to an allowlist. pnpm link --global puts taskcell on your PATH.
Prefer a native app? See Install the desktop app.
Claude Code, Codex and other agents that read Agent Skills can walk you through the setup: on this computer, on a server for a team, or in GitHub Actions or GitLab CI. They ask where your code and tasks are, run each step, check it, and stop for the steps only you can do (tokens, OAuth apps, DNS). Paste this into your agent:
Set up Taskcell for me: https://github.com/spietrza/taskcell
Clone it and follow .agents/skills/setup-taskcell/SKILL.md (the same skill is at https://taskcell.dev/.well-known/agent-skills/setup-taskcell/SKILL.md).
To run the factory from GitHub Actions instead, with no host of your own, follow docs/onboarding-another-repo.md. For an always-on host, see docs/deploy.md. For a browser cockpit with a task board, live transcripts and run records, run pnpm hub --repo /path/to/repo (docs/hub.md).
| Task source | How to use it | Review surface |
|---|---|---|
| GitHub Issues | run --github owner/repo#n, watch --source github or the Actions workflows |
Pull request |
| GitHub Projects v2 | run --project <n>, watch --source project |
Pull request |
| GitLab Issues | run --gitlab group/project#n, watch --source gitlab |
Merge request |
| Linear | run --linear ID, watch --source linear |
PR or MR, by the repo's origin |
| Provider | --provider |
Credential |
|---|---|---|
| Claude Code CLI (default) | claude |
CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY |
| OpenAI Codex CLI | codex |
CODEX_API_KEY / OPENAI_API_KEY, or CODEX_AUTH_JSON (ChatGPT subscription) |
| Cursor CLI | cursor |
CURSOR_API_KEY |
| z.ai GLM Coding Plan | zai |
ZAI_API_KEY |
| OpenRouter | openrouter |
OPENROUTER_API_KEY |
| Anthropic-compatible endpoint (proxy) | a customProviders entry in .taskcell/app.json (--provider <name>); meridian stays as a CLI alias for MERIDIAN_BASE_URL |
keyEnv names the key variable, or omit it for a proxy that holds its own auth. E.g. a self-hosted proxy such as Meridian or CLIProxyAPI; see docs/MERIDIAN-provider.md as an example |
Any stage can run on a different provider or model: --review-provider codex for cross-provider review, --provider-model, --review-model, --escalate-model for a stronger model after a failed repair, and --fallback-provider for outages. See docs/task-sources.md and docs/cli.md.
A starting point, not a rule. Aliases (sonnet, opus) follow the newest model; a full id pins one.
| Stage | Use | How | Why |
|---|---|---|---|
| π§ Spec and plan | The strongest reasoning model you have | --spec-model opus, --plan |
A wrong spec costs every later stage. This stage is short, so the strong model is cheap here. |
| βοΈ Implement | A mid-tier coding model | --provider-model sonnet |
Most of a run's tokens are spent here. |
| πΈ Implement on a budget (easy issues, experimental) | A flat-rate plan or a cheap model | --provider zai, or --provider openrouter --provider-model <model> |
Works on small, well-specified issues. Keep --escalate-model on. |
| π Repair escalation | A pinned top model | --escalate-model claude-fable-5-2 |
Only runs after a second failed gate repair, so it costs nothing on a clean run. |
| π Review | A different model family from the implementer | --review-provider codex |
A model shares its blind spots with itself. If you have one provider only, review on a stronger model than the one that wrote the code: --review-model claude-fable-5-2. |
| β Conformance (opt-in) | A strong model | --conformance --conformance-model opus |
It checks the diff against the acceptance criteria, where a miss means the wrong thing ships. |
| π Outage fallback | Another vendor | --fallback-provider codex |
Rate limits and outages are per vendor. |
Tip
Never let the cheapest model in the run be the reviewer: the review is what makes a cheap implementer safe.
The flags work on run and watch; in the GitHub Actions workflows the same names are the inputs of the with: block.
| β 1. Recommended | 2. One subscription | π§ͺ 3. Budget (experimental) | |
|---|---|---|---|
| π§ Spec | Claude Opus | Claude Opus | Claude Opus |
| βοΈ Implement | Claude Sonnet | Claude Sonnet | DeepSeek V4.1 Flash on OpenRouter |
| π Review | GPT-5.6 Sol on Codex | Claude Fable 5.2 | Claude Fable 5.2 |
| π Escalation | Claude Fable 5.2 | Claude Fable 5.2 | Claude Fable 5.2 |
| π³ You pay for | Claude plan + ChatGPT plan | Claude plan | Claude plan + OpenRouter credit |
| π Track record | In production here from June to November 2026: 90+ merged pull requests reviewed | In production here since November 2026: nearly 80 merged pull requests reviewed | Early pilot: passed review on an easy issue where Sonnet's change did not |
1. Recommended: the reviewer is from another vendor. Taskcell's own factory ran on this setup for four and a half months.
--spec-model opus --provider claude --provider-model sonnet \
--review-provider codex --review-model gpt-5.6-sol \
--escalate-model claude-fable-5-22. One subscription: the reviewer is a stronger model from the same vendor. Use it when you have a Claude plan only, or when the second plan runs out of quota.
--spec-model opus --provider claude --provider-model sonnet \
--review-model claude-fable-5-2 \
--escalate-model claude-fable-5-2 --fallback-provider codex3. Budget: a cheap implementer under a strong reviewer. On an easy issue it passed review where Sonnet's change did not; on a harder one it needed three repairs and left four times as many review notes. Use it on small, well-specified issues.
--spec-model opus --provider openrouter --provider-model deepseek/deepseek-v4.1-flash-1017 \
--review-provider claude --review-model claude-fable-5-2 \
--escalate-model claude-fable-5-2--provider zai (z.ai GLM Coding Plan, flat rate) fits the same slot as OpenRouter in setup 3. We have not tested the full GLM 5.3 yet; GLM 5.3 Flash did not pass review on the easy issue.
Taskcell runs coding agents on untrusted input and treats the agent as hostile. These controls sit around it:
- Sandboxed agent. The agent runs in a Docker container as a non-root user, with all Linux capabilities dropped except three file-ownership ones,
no-new-privileges, and memory, CPU and PID limits. Secrets reach it through a file on an in-memory tmpfs, not through command-line arguments. - No repository token in the sandbox. GitHub and GitLab tokens stay on the host. The host, not the agent, pushes the branch and opens the PR.
- Egress allowlist and LLM proxy.
--egressputs the sandbox on an internal network whose only way out is a proxy that allows listed hosts.--llm-proxyalso keeps the model key in a sidecar and gives the sandbox a per-run nonce. With--llm-proxy, a Codex ChatGPT-planauth.jsonstays on the host too when the run also uses Claude, Z.ai or OpenRouter (Codex as reviewer or fallback); a Codex-onlyreview-pr,review-mrorresearchrun with--llm-proxystarts only the Codex sidecar, while a Cursor run, orrun/watch/spec/revise-prwith only Codex, refuses to start (details). - Secret gate on the outgoing diff. Before anything is pushed, the diff is scanned for secret patterns and for the exact values of credentials injected into the run. A hit pushes nothing.
- CI config is never copied back. Changes to
.github/workflows/,.github/actions/,.gitlab-ci.ymland.gitlab/**.ymlare dropped, so agent code cannot become CI code. - Trust gates on input. The GitHub Actions workflows only start for allowlisted senders, and
watch/watch-prsskip issues and PRs whose author is neither a repository member nor allowlisted. On GitHub, comments count as instructions only from repository owners, members and collaborators, the issue author, or logins you allowlist with--feedback-authors. On Linear, only workspace members count. GitLab has no association model, so set--feedback-authorsthere to make comment trust a boundary; once it is set, comments from unlisted authors are ignored. - Humans merge. Taskcell opens pull requests and never merges them. The approver runs in shadow mode and only records what it would decide.
How these fit together: docs/security/boundaries.md. How they map to the OWASP Top 10 for Agentic Applications and the OWASP Top 10 for LLM Applications: docs/security/owasp-mapping.md (a self-assessment, not a certification). Our own multi-agent security review in November 2026 confirmed 14 findings (2 high); 13 shipped in 1.13.0 and the last (a low) in 1.16.1, so all 14 are fixed: docs/security/review-2026-11.md. To report a vulnerability, see SECURITY.md.
| Page | What it covers |
|---|---|
| docs/architecture.md | Design principles, one run end to end, layers, library use |
| docs/task-sources.md | GitHub, Projects, GitLab and Linear sources |
| docs/auth.md | Subscription vs API key, local secrets, 1Password |
| docs/cli.md | Models, providers, decision models, one-shot commands, white-label mode, fork-and-select, sandbox image, cost and limits |
| docs/autonomous-loop.md | Watch loop, routing labels, PR review, GitHub Actions, metrics, approver, retrospective memory, Proof of Work, visual proof |
| docs/skills.md | Bundled skills, custom skills, per-provider injection |
| docs/hub.md | The browser cockpit (taskcell hub) |
| docs/onboarding-another-repo.md | Run the factory on your repo with GitHub Actions |
| docs/onboarding-linear.md | Linear setup |
| docs/deploy.md | Always-on host (Docker, Coolify) and garbage collection |
| docs/approver-policy.md | Approver policy reference |
| docs/CURSOR-provider.md, docs/MERIDIAN-provider.md | Provider guides |
| docs/security/boundaries.md | Security boundaries and the host LLM proxy |
| docs/security/owasp-mapping.md | OWASP self-assessment |
| docs/evals-and-guardrails.md | Evals and guardrails: where Taskcell stands |
| CHANGELOG.md | Release notes |
| What | Where | How to read it |
|---|---|---|
| Run records (logs, diffs, proof of work) | .taskcell/runs/<task>/ in the repo checkout |
Hub β Runs, or the files |
| Metrics (cost, tokens, time per stage) | .taskcell/runs/metrics.jsonl; durable copy in metrics.jsonl on the taskcell-metrics branch |
taskcell stats (--branch taskcell-metrics in CI setups) |
| Lessons from closed factory PRs | lessons.jsonl on the taskcell-metrics branch |
taskcell lessons list, Hub β Lessons |
| Approver decisions | decisions.jsonl on the taskcell-metrics branch |
taskcell stats --approver, Hub β approver card |
| Retrospective memory given to the agent | .taskcell/memory/retrospective.md |
taskcell memory |
| Hub projects, teams, sign-in, audit log | the hub config dir (TASKCELL_HUB_CONFIG_DIR) |
the Hub; taskcell audit verify |
Details: docs/audit.md and docs/autonomous-loop.md.
pnpm install
pnpm typecheck
pnpm testStrict TypeScript, ES modules, Vitest with tests next to the code (*.test.ts). Docker integration tests run when Docker is present and skip otherwise. See CONTRIBUTING.md.
