Quickstart

1. Set up

curl -fsSL https://titah.dev/install | bash

The installer checks your OS and Node version, installs titah globally via npm, and runs titah init — which finds a provider from your environment or a local endpoint and writes ~/.config/titah/titah.json. Pass -s -- -y to accept the first thing it finds without a dialog.

Prefer to run the steps yourself? See Installation for the npm and from-source routes.

2. Check what you have

titah doctor --probe

Read the output before going further. The two lines that matter most:

• External agents — whether claude and opencode were detected. Missing ones are listed as unavailable with the command that was not found, never hidden.
• Models missing contextWindow — automatic compaction is off for those. See Context & compaction.

3. Open the TUI

titah

A local server is spawned on a random port and the TUI attaches to it. The opening screen centres the prompt beneath the ASCII logo. Type a question and press Enter.

Esc cancels a running turn. Ctrl+D, /exit, or Ctrl+C twice quits.

4. Ask it to do something real

find every place we parse a date string and tell me which ones assume UTC

Titah reads, greps and globs on its own. Anything that would change a file stops and asks first — y once, a always, n deny. That is Build Manual mode, the default.

5. Delegate a question

If claude or opencode is installed:

@claude does the retry logic in src/core/rpc.ts have an unbounded backoff?

Only the final answer enters your context. The full transcript is written to tool-output/ and referenced by path — injecting it whole would blow out the context window within two or three delegations. A second @claude resumes the same external conversation.

6. Ask everyone at once

/consensus is the caching approach in src/core/storage safe for concurrent writes?

Every available external agent is called in parallel, each answer is shown as its own block, and Titah’s own model then synthesises: what they agree on, where they differ, and which is wrong.

Disagreement is the reason you asked several agents, so the synthesis prompt explicitly forbids inventing agreement that is not there.

!!! note “About the cost line” /consensus calls every available agent, so the $ shown is the sum of what each reported. For Claude Code on a subscription that figure is an API-price equivalent, not a bill — what you actually spend is rate-limit quota. What you will feel more is time: consensus waits for the slowest agent.

7. Undo everything from the last turn

titah undo

Or Ctrl+X U inside the TUI. One snapshot per turn means one undo reverts the whole turn — files the agent created are deleted too, because a half undo that leaves new files behind is not an undo.

Headless, without the TUI

titah run "how many .ts files are in src/? Use glob."
titah run -a build-auto "fix the failing tests"

titah run executes the core in process, not over HTTP — the same agent loop and the same storage, just skipping the network layer.

For automation, remember that with no client connected any tool needing a dialog is auto-denied. Use --auto or an explicit permission.allowlist. See Permissions & undo.

Next steps

• Configuration — make the model, agent and permissions yours.
• The TUI — every key, and why the defaults are opencode’s.
• Tools — what the model can actually do.
• Modes & custom agents — Plan, Build Manual, Build Auto, and your own.
• Structured output — when the caller is a script rather than a person.
• Cost & limits — read back what you have spent, and bound what comes next.