Calandria

Run Claude Code, Codex and Antigravity in parallel across every project, from any browser.

Calandria is a self-hosted web control room for your coding agents. Run it on your laptop or a server and use the same workspace from your computer, tablet, or phone. Every task gets its own persistent agent session in its own git worktree. Your existing Claude Max, Pro, or ChatGPT subscription covers it. No API key needed.

calandria.dev · Docs · Run locally · Self-host · Request a feature

Why Calandria

• Use it from anywhere. Deploy once, then manage agents from any device with a browser.
• Run many tasks without juggling terminals. Each task has its own worktree, branch, transcript, and agent session.
• Know where you're needed. A cross-project inbox lists the sessions waiting for an answer while the rest keep working.
• Review every change. Read the diff next to the conversation, then merge, resolve conflicts, or open a pull request. Once a PR exists, its state (open, merged or closed, checks green or red, review approved or not) stays live on the task, so you don't need to open GitHub, and one button squash-merges it from there. Where the repo allows auto-merge, that click queues it and GitHub lands the PR the moment its checks pass.
• Catch a red build. A PR whose checks go red raises its task into the same "Needs you" inbox a parked question does, names the job that broke, and offers a one-click Fix CI that starts a turn seeded with the failing job's log, even on a task already marked done.
• Start from the latest base. Calandria fetches the base branch before cutting a task's worktree, so a PR merged on GitHub doesn't leave new tasks building on stale code. It also tells you when your own checkout has fallen behind. A local base that is ahead or has diverged keeps its unpublished work. PR creation checks that this inherited work is present on the remote base before pushing.
• Point a task at any branch. A task can use its own base branch instead of the project default: it's cut from it, synced to it, merged into it, and PR'd against it. Several tasks can land on one feature branch while the rest keep shipping to main. A tag can set that branch for a whole plan. It shows when the branch has fallen behind the project default ("3 behind main"), with a Sync that merges the default into it, and a Create for a base branch nothing has made yet. Left alone, an integration branch drifts, and every task cut from it starts stale.
• Say how work lands. A project lands by merge or by pull request, and every session in it is told which. On a repo whose base branch requires a PR, agents stop reaching for a Merge that GitHub will reject, and so does the diff rail: Create PR becomes the primary button. It opens an editable title field with an optional Conventional Commit format hint. The local merge says up front that it can't be pushed. Calandria can read the branch's rules from GitHub and preselect the answer. A PR a session opened by hand, in a terminal, is linked to its task at the end of the turn, so it gets the same chip, state polling and reclaim as one opened through the app.

How it works

1. Create tasks and, if you like, chain them into a pipeline.
2. Calandria gives each task an isolated worktree and starts it when its dependencies finish.
3. It alerts you when a session needs an answer.
4. You review the diff and merge.

Project context is written once and sent into each task. Turns run on the server and transcripts are saved, so a browser reload or a sleeping laptop doesn't interrupt anything. /clear starts a fresh context window and keeps the task's history as a summary.

Each session is told to push bulk context collection into subagents. After two read-only commands in a row, the third goes to a subagent instead, which reports back its conclusions and file:lines rather than pouring file contents into the session's own context window. This overrides the CLI's own default, which runs that work directly in the shell and leaves subagents unused unless you ask for one; the private notes repo's DELEGATION.md has the measurement behind it. Set CALANDRIA_DELEGATE_COLLECTION=off to leave sessions on the CLI's defaults.

When a Claude turn starts background shell work or schedules a wakeup (ScheduleWakeup, CronCreate, /loop), the session stays open after the model stops. The task shows "working in background" or "waiting to wake at 12:00" with its age; when the work finishes or the wakeup fires, the agent continues. No deadline applies by default, so a recurring /loop holds the session open until you stop it. CALANDRIA_BACKGROUND_LINGER_MS adds an optional auto-cut (a wakeup past it is cancelled and noted in the transcript), and CALANDRIA_BACKGROUND_LINGER=off disables lingering and reports every pending wakeup as cancelled at the end of the turn. A message you send while a session is lingering goes straight in and starts the next turn instead of waiting in the queue.

Because that wait has no deadline, a session can also sit live and silent waiting on something that already finished: a poll against a dead service, a watcher loop that never exits. After 20 minutes with no output and no tool call, the task card and the session show "no activity for 34m" beside the running indicator. Calandria doesn't stop the turn for you, since the server can't tell a wedged wait from a slow one and cutting a real 40-minute test run would be worse. It's also not a "needs you" item, since nothing needs an answer. The card's one action is a Stop this turn chip below that line: it arms on the first press and stops on the second, since a stray click is easy to make on a list. The session view carries no such chip; the composer's Stop covers it, next to the transcript to judge against. CALANDRIA_TURN_IDLE_MS moves the window, and 0 turns the note off. A turn parked on a question or a permission card is never marked, since that wait is meant to be open-ended.

By default, the session gets no nudge about this. Set CALANDRIA_TURN_IDLE_NUDGE=1 and a turn that goes quiet is sent one line asking it to recheck what it's waiting on. This fires at most once per turn, only while the session is lingering (a build or tool call in flight is never interrupted), never on a scheduled run, and never ahead of a message you've already queued. The transcript records that it was sent.

What you get

• Parallel, isolated tasks: work across several repositories without agents mixing files or branches.

• Repair a worktree in one click: a turn never runs in your real checkout, so a task whose worktree can't be prepared stops instead. When the cause is stale git bookkeeping (a lock file from a crashed git, a worktree still registered at a directory that's gone), the error says so and offers Repair worktree: it clears the lock, prunes the registration, cuts the checkout again, and re-sends the message. Calandria names causes you have to fix yourself (a full disk, a detached HEAD) just as plainly, including on unattended scheduled runs.

• Agent settings can't change behind your back: Claude Code re-reads a task's .claude/settings.json at the start of every turn, and its hooks run shell commands with no permission prompt. That file lives in the task's own worktree, so a turn could write what the next turn obeys. Calandria checks it before each turn and, if it changed since the turn that ran last, holds the turn on a card showing the diff. Approve it and the turn runs; decline and it ends before the agent starts. Unattended and scheduled runs always decline.

• Web-based and self-hostable: run Calandria on your own machine or server and reach the same workspace from desktop or mobile.

• Work Center: a titlebar pill shows how many tasks are working and how many need you. It opens a list of everything that needs a decision, is working, or is waiting, across every project, with Allow once, Deny, Acknowledge and Snooze inline. On a phone it is the Work tab. An agent can also file a review of its code or a Markdown document; a pending review shows up as one item to decide, and the task gets a REVIEW tab (a Review segment on a phone) showing the exact diff or document the agent submitted. You accept it, request changes with feedback the agent receives as its next message, or waive a required review with a reason. Accept never merges: merging stays in the landing controls. Review requests are off by default (Review submissions).

• Snooze a task: park it until an hour from now, tomorrow morning, or a date you pick. It is hidden from the Work Center and every count until the deadline, then returns to the category it left, marked as snoozed.

• Start at the usage-window reset: when a subscription limit stops your turns, queue a task to start (or a stalled session to resume) a minute after the reset the plan meter reports. This runs server-side with no tab open. Settings → Run defaults can queue that resume for you whenever a turn dies on the limit, per agent, off by default.

All features

Supported agents

Calandria supports the Claude Code, OpenAI Codex and Google's Antigravity (the CLI behind Gemini) environments end to end. The UI calls each coding CLI an environment in Settings → Models. Some task editors still label it Agent. The API keeps the field name agent. Choose an environment per task, or connect only the one you use. All three work with subscription login, and API keys stay optional, except in a container, where Antigravity needs one because its CLI stores its token in the OS keyring. Codex tasks select permissions and a sandbox independently. An inherited sandbox uses the Settings → Run defaults value, then the permission mode's default mapping. Codex approval requests land on the same permission card a Claude prompt does, and a workspace-write Codex turn can still commit from its worktree. On a Linux host that blocks the user namespaces Codex's sandbox needs, Settings → Models displays the fix when you connect the Codex environment. Calandria blocks the sandboxed modes instead of running turns whose every command fails.

Codex provider HTTP 503 failures show as temporary upstream outages, with the provider's diagnostics and request ID. Codex retries stay in the current session and retain command tracking. If a failure ends the turn, check any command listed with an unconfirmed status before resuming the same task. Calandria keeps the session, worktree and queued messages.

Choose Effort in the New task or Edit task dialog to override the environment's default for that task. The picker offers the same levels as the session controls. Agents can select a level when calling suggest_task with reasoning.

Settings → Models separates Environments, the coding CLIs that run tasks, from Providers, the endpoints, credentials and model policies that supply models. Signing in to an environment adds its bundled provider. You can add LiteLLM, Ollama, LM Studio, and custom providers separately.

Antigravity's bundled provider reads the available models from agy models. New models appear when the CLI reports them. Use Refresh in the provider's Models tab to reload the catalog. If the CLI cannot report its models, Calandria uses the last successful catalog or its built-in fallback.

Agent support, permissions, and usage details

Local models

Claude Code and Codex can run against a local model server. Open Settings → Models, select Add provider, and add Ollama (http://localhost:11434) or LM Studio (http://localhost:1234). Test the connection and choose which reported models stay on. Select the provider and model for a project or task. Claude Code uses ANTHROPIC_BASE_URL, and Codex uses a provider entry Calandria adds for the turn. The provider's Connection tab lets you test the server.

Choose the model before the environment. In the model picker, choose a family, then a version, then a provider source when more than one provider serves that version. Calandria records Ollama and LM Studio turns at zero cost. It records every Custom endpoint turn as unpriced. Unpriced turns stay out of cost totals, and the figures that omit them say so. Local and custom providers show no context percentage when the catalog has no window size, so the chip reports tokens used. A cloud session can also delegate a single task to the local model with suggest_task's provider: "local". For self-hosting, set CALANDRIA_LOCAL_MODEL_BASE_URL to seed the first local provider row at boot. After that row exists, its Settings → Models configuration wins.

Recipes and the allowlist

LiteLLM gateway

A LiteLLM proxy supplies models to the existing environments. Open Settings → Models, select Add provider, choose LiteLLM gateway, enter its endpoint and key, test the connection, and choose the models to allow. Select that provider and a model for a project or task. For self-hosting, CALANDRIA_LITELLM_BASE_URL and its related variables seed the first LiteLLM provider row at boot. After the row exists, its stored configuration wins.

Settings-created providers use the gateway key. The provider API also supports two billing modes:

• Billed to the gateway's own virtual key.
• Billed to your own plan, with the CLI's login forwarded through the gateway.

Every turn carries tags naming the project, task and agent, so LiteLLM's spend views break down by task. A Claude task also joins to LiteLLM's spend log by session id, with no configuration needed on either side. Codex and Antigravity tasks route through the gateway too. Each uses the credential its CLI reads and always bills the gateway key.

The provider row in Settings → Models shows how many models are on. Its Connection tab tests reachability and authentication. Its Models tab manages the allowlist.

A turn that exceeds the key's budget parks its queued follow-ups and offers a Retry, the same recovery path as a dead login. Gateway spend is an estimate from the gateway's own price table and is marked ≈ in Insights. A cache-hit column also shows whether prompt caching survived the proxy's translation.

Setup, billing modes and the two caveats

Preparing a project for parallel tasks

Every task is its own git worktree, so it starts from a checkout holding tracked files and nothing else: no .env, no node_modules, no build output. Several run at once. Repos that assume one copy of themselves on the machine hit this as port collisions, a shared dev database, or a first turn spent working out how to install dependencies.

The worktree-ready skill in skills/ audits a repository for these problems and proposes the repo-side fixes. It works in Claude Code and Codex:

scripts/install-skills.sh          # both agents, user scope

Then ask a task in that project whether it's ready to run five at a time.

Run locally

You need Node 22.12+ on macOS, Linux, or Windows, and at least one supported agent CLI. Mermaid diagrams require a modern browser, including Safari 17.4 or newer.

npm install
npm run build
npm start

Open http://localhost:3000. The first-run wizard connects Claude Code or Codex and walks you through a short tutorial.

Windows runs natively with the same three commands. It needs Windows 10 1809+ or Server 2019+ (for ConPTY, which the terminal uses), Git for Windows on PATH, and Node 22.12+. The typecheck, unit, and end-to-end suites all run on windows-latest in CI. WSL2 also works; it runs the Linux build unchanged. See Windows setup, both ways.

Prefer a container? A multi-arch image (linux/amd64 + linux/arm64) is published publicly. latest is the newest tagged release; edge tracks nightly builds of main.

docker pull ghcr.io/calandria-dev/calandria:latest

Use npm run dev only when developing Calandria itself. For Docker tags and provenance, authentication, networking, and secure remote access, see the self-hosting guide. To layer site-specific CLIs and config on top of the published image, start from examples/overlay/.

One instance per database

Calandria locks calandria.db at boot and won't start if another process already owns it, naming the holder. Two servers sharing one database would overwrite each other's running tasks. Give a second instance its own CALANDRIA_DB_DIR.

Disk usage

The database does not grow forever. A retention sweep runs on the schedule ticker and removes the record of finished tasks: transcripts, review comments, retired sessions, and staged attachments after 180 days, spend rows after 400 (longer, so Insights keeps its full 180-day range). It then checkpoints the WAL so the space is reclaimed. Live tasks are never touched. CALANDRIA_RETENTION=off keeps everything. The windows and the opt-in VACUUM are in the self-hosting guide.

Per-task worktrees are the bigger disk cost (a full checkout each) and have their own switch. Calandria warns in the log and in Settings → Storage once the worktrees directory passes CALANDRIA_WORKTREES_DISK_WARN_GB (default 20). Reclaiming them in bulk is manual unless you set CALANDRIA_WORKTREE_RETENTION=on, which removes the checkouts of finished tasks after 14 days. It never deletes the branch, and it skips (and names) any checkout holding uncommitted edits or unmerged commits.

The prompt case doesn't wait on a clock. When a task's work lands (its pull request reports merged, or Calandria merged the branch locally), the session header offers Reclaim: fast-forward the local base branch from origin, remove the worktree, delete the local branch and mark the task done, in one click. Project settings can have the server do that by itself (off by default). Neither path discards uncommitted edits, or commits the remote never saw, without you confirming it.

Backups and upgrades

npm run backup takes a hot backup with the app running: a WAL-safe VACUUM INTO snapshot of the database plus uploads, keys, and the agent CLI logins, in one timestamped archive. Don't cp a live SQLite database. See Backup & restore for the flags, the cold-copy alternative, and the restore procedure.

Take a backup before upgrading, because upgrades only run one way. Each build stamps the database with the schema version it understands, and an older build pointed at a database a newer one already migrated won't boot. Rolling back means re-pinning the previous image tag and restoring that backup. See Rolling back an upgrade.

Privacy

Calandria has no telemetry and no analytics. It makes no outbound requests you didn't configure. Network traffic comes from your agents, your git remotes, and your own integrations.

Community

• Request a feature or share an idea
• Ask a question
• Report a bug
• Contribute

See COMMUNITY.md for where each kind of conversation belongs.

Documentation

Everything below is also published, rendered and searchable, at calandria.dev/docs: the same files, so either reader is current.

• Installation and local development
• Features
• Document collaboration
• Agents
• Insights and usage
• Managed services
• Review submissions
• Bundled agent skills
• Self-hosting
• Troubleshooting
• Windows: native and WSL2 setup · platform notes
• Desktop app spike · desktop e2e testing
• Architecture

License

Apache-2.0

Name and lineage

In a CANDU reactor, a calandria is the vessel that hundreds of parallel fuel channels run through, each working in isolation inside one coordinated machine, which is what this software does.

Calandria began as a fork of Operator by @iishyfishyy. It keeps Operator's Apache-2.0 license; see LICENSE and NOTICE. Calandria is not affiliated with the upstream project or its hosted service. File bugs and ideas for Calandria in this repo's issues.