Titan docs

Titan is a native macOS terminal built on libghostty. It runs shells, Claude Code sessions and agents like pi side by side, with a browser they can drive and actions you can script.

Install

The latest release is a disk image, signed with a Developer ID and notarized by Apple. Open it and drag Titan to Applications.

  • macOS 26 (Tahoe) on Apple Silicon.
  • Claude Code for Claude panes. Without it, shells work as usual.
  • Titan checks for updates once a day and installs them from the tab bar.

Set it up

  1. Install an agent. Claude Code for Claude panes, and pi or any other agent you like for shells. Titan finds Claude Code wherever it's installed (npm, nvm, Volta, Homebrew, the native installer); if it doesn't, set claude-path = /path/to/claude (Settings › Agents › Claude Code).
  2. Open the config with ⌘,. It's ~/.config/titan/config, with every setting written out and commented on first launch. Titan reads your Ghostty config first, so your font and theme carry over.
  3. Save. Titan applies changes within a second. A line it can't read shows in a bar with its line number.

To let agents open panes and drive Titan, set remote-control = true. The config builder writes a starting file for you.

Agents

Use Titan's own Claude pane, the claude CLI you already know, or another coding agent such as pi or Codex. Each one runs in a pane, can open panes and drive the browser beside it, and stays out of the panes that aren't its own.

⌘N · New Claude Session
you Start the dev server and check the page
▸ Ran 2 commands
▸ titan_do new_split direction=right command="npm run dev"
▸ browser_navigate localhost:4173 · browser_click "Break"
The page loads and Break sets the timer to 05:00.
The dev server is still running in a pane on the right.

Claude Code as a conversation

The same claude you have installed, with your settings, CLAUDE.md, skills and MCP servers, drawn as a feed with its own composer, model picker and context ring. Titan gives it its browser and pane tools as an MCP server, mcp__titan__*.

Uses your Claude Code login. There's no API key to paste into Titan.

Claude paneclaude in a shellpi, Codex & others
Status on the tab, ⌘J to the waiting one●●● from the escapes it sends
Opens panes, reads them back● titan_do● titan_do● titan do
Drives the browser beside it● browser_*● browser_*● titan browser
Kept to its own panes●●●
Replies set as Markdown, /diff, pages in the feed●its own TUIits own TUI
Keeps the Mac awake while it works●●–

The Claude pane

⌘N opens a box for your first prompt, with the folder and model as chips already filled in: write, press Return, and a Claude Code session starts in a new tab, drawn as a conversation with an input box of its own. ⌘O starts one in a folder you choose, ⌘K goes to any open session or resumes a past one, and Change folder… on the folder chip above the input starts one there in the same pane. The + in the tab bar offers New Session and New Tab. With nothing open, Titan shows a start screen on your Claude pane background rather than a shell. It runs Claude Code in its structured stream mode, so replies, tool calls and their output arrive as messages instead of a scraped screen.

Send while it works
↩ sends at once, and Claude takes the message in at the running turn's next step. ⌥↩ queues it for when the turn ends instead.
Run what it suggests
Shell code blocks in a reply get Run and Run in a shell. Output streams in under the block. Nothing runs without the click. Every code block shows Copy when you hover it, beside its language: it copies the code as written, and a shell block's copies the commands of a $ cmd transcript without the prompts. Copy on every block new in 0.29.
See what changed
/diff opens the git status beside the conversation: the uncommitted changes, recent commits and stashes. The +/− chip above the input counts the uncommitted lines, and empties once they're committed. Both follow the session into a worktree it works in.
It knows Titan
Every session is told where Titan's manual and changelog are and reads them without asking, so you can ask it what Titan can do, how to do something or where a setting is. New in 0.20.
Sessions read each other
A session can look things up in your earlier ones instead of loading them whole: ask it to “find the session where we fixed the login test and carry on from there”. session_find searches titles, folders and content, session_grep searches one session, and session_read reads its prompts, replies and tool calls. These don't ask first, and reach any project's sessions on that Claude account, never another account's. Tool output stays out of them: session_output shows one entry of it and asks you first. Secrets Titan recognises, like API keys and passwords, show as [redacted]; it can miss unusual ones. session-tools = false, or Settings › Agents › Read other sessions, turns them off. New in 0.20.
Claude's questions, as a form
When Claude or a skill asks you something, the card shows each question with its options to pick, one or several, and Other for an answer of your own. Answer sends them back.
Every path is a link
File paths and URLs in the feed are clickable. A file opens beside the pane at its line, in a built-in viewer or your $EDITOR. Markdown opens formatted, with a button for its source.
Select from anywhere
Drag to select across a reply's text, code and tables, starting on the text or in the empty space beside and between it, as on a web page. What you select is copied when you let go.
Pages and diagrams, live
HTML and SVG files Claude writes show up in the conversation as live pages. A mermaid block is drawn as a diagram, in the theme's colours.
Start on a branch
Typing in the ⌘N box's folder chip also searches the project's branches, local and remote, however old: DA-253 finds feature/DA-253-…. Picking one starts the session in a worktree on that branch, or where it's already checked out, so it doesn't move the branch other sessions in the project's folder are on. New in 0.33.
Tips while it works
Under the turn's running time, a key or command worth knowing, a new one every 12 seconds, with your own keys if you've rebound them. tips = false hides them. New in 0.27.
A worktree each
⇧⌘N starts a session in a git worktree of its own, on a new or existing branch, so two sessions can work on one repository without stepping on each other. A session works directly in its folder unless you ask for one. See Worktrees.
Where the work stands
sidebar-status = true adds a card at the foot of the left sidebar for the selected session: its branch, worktree, pull request and its review, changes and build, each opening where it says. Builds come from GitHub or a Bitbucket Server, where Jenkins and other CI report, so they need no token of their own. It uses the same logins as /pr and only reads with them.
Ask Claude about a pull request
The Review pane that /pr opens has an input at its foot: with nothing typed Claude reviews the whole pull request, or ask it something. It works in a session beside the review, asks before doing anything and reports to you; nothing is posted.
Pick a pull request
Review Pull Request… in the palette takes a link or a number. With review-list = Work, git.example.com/PROJECT/repo in the config it also lists that repository's open pull requests, for folders on that Claude account. New in 0.30.
Model, effort, context
A model picker, an effort slider and a ring for how full the context window is. Permission modes run from asking every time to YOLO.
Your plan's usage
/cost or /usage draws your plan's usage as a card: a bar each for the session, the week and usage credits, when each resets, and what used it. A small ring beside the context ring shows the same live, amber from 80% and red from 95%; click it for both limits. On an account whose answer leaves the limits out, like an organisation's, Show in Claude Code opens Claude Code's own usage screen beside the pane. New in 0.16.
@ and /
@ fuzzy-finds files to mention. / lists the commands and skills installed for that session, with their descriptions. /plugin install name@marketplace (or uninstall, enable, disable) changes Claude Code's plugins and reloads them in the same conversation; /plugin alone lists them.
Attach anything
Paste or drop images and files into a conversation, drop them on a tab, or pick them with the 📎 button beside the input: a Claude session attaches them, images as images, and a shell types their paths.
Dictate
With Hex installed, a microphone sits beside the send button: click and speak, click again and the words go into the box, not sent.
Know which session needs you
A Claude session's icon is a small solid that says how it's doing: it turns while the session works, holds still as a hexagon when it waits on you, becomes a twisted infinity when it's done and splits apart when it fails. Each session keeps its own solid, so workers are easy to tell apart. A split tab shows its Claude session's icon and name, whichever pane has focus. ⌘J jumps to the one that's waiting. New in 0.25.
Projects in the sidebar
sidebar-projects = true puts the left column's tabs under a heading for each repository, worktrees included, or folder. Click a heading to fold it, hover it for a + that starts a session there, and drag it to move the project. New in 0.24.
New Project
⇧⌘O gets you a project folder three ways: open one you have, clone one of your GitHub repositories or any git address, or start from scratch, with a private GitHub repository if you ask for one. It ends in ⌘N's box with that folder chosen. New in 0.24.
More on hover
Rest the pointer on a tab, in the left column or the top row: its status, when it started and was last active, model and effort, folder, branch, how full the context is, what it's waiting on, and the tab's other panes. Top-row tabs also show a picture of their panes. It reads only what's on your Mac, so it never waits on the network. New in 0.22.
The session's menu
⋮ in a Claude pane's header, or right-click its tab to act on a session without going to it: Export, Copy Session ID, Fork, Hand Off, Continue in another account and Usage. Hand Off and Usage each send Claude a message. ⋮ also holds Rename, Git status, Open Browser, Archived Sessions and Archive Session. New in 0.22.
Archive and come back
The archive button in a pane's header closes a session and keeps its conversation. Archived Sessions resumes it: the last 24 hours are listed under the tabs in the left column, and all of them from there or from ⌘K, the palette or ⋮. Each row says how long it has, because Claude Code, not Titan, deletes a transcript left unused for cleanupPeriodDays in that account's settings.json (30 days by default). New in 0.22.
A Claude session in Titan: replies with tool steps folded into one line, and a permission card asking to read the shell beside it
Replies set for reading, steps folded, permissions inline

Fork & handoff

Two ways to take a conversation somewhere new without losing the one you're in. Each new session opens with a line back to where it came from: Forked from “…” or Handed off from “…”. Click it to bring the parent forward, or resume it if it's closed.

/fork [note]
Opens a new session with this one's whole history, as a conversation of its own, so it can try another approach while the parent carries on unchanged. The note, if you give one, waits in its composer.
Fork from Here
On any reply in the feed: a new session with the history up to that reply, for going back to a point before things went sideways.
/handoff [goal]
The session writes the opening message for a fresh one with only what matters for the goal: decisions, where the work stands, files, what failed, next steps. It opens in a new tab with the same folder, worktree, account, model, effort and permission mode, the message in its composer to edit before sending, plus a pointer to the old session, which it can search and read for anything left out.
Compact ahead
When a turn ends past compact-ahead percent of the context window (60 by default; Settings › While it works), a copy of the conversation is compacted in the background while you keep working, and the session moves onto it at its next pause. The context ring pulses while it runs. compact-ahead = 0 leaves compacting to Claude Code.
Export as Markdown
Save or copy a conversation from Export in the session's menu, or from the palette: prompts and replies in full, each tool call one line, no tool output. These are for you: to send one to someone, use Share Conversation.

Workers

New in 0.20.

A Claude session can split work across sessions of their own: ask it to “run these three fixes through workers, Haiku for the docs”. Each opens in a tab you can watch, and reports back when it finishes or needs you, so the session that started it never has to keep checking.

Each with what its task needs
Its own model and effort. Workers work directly in their folder, where they share its files and can step on each other, so ask Claude to give them worktrees when that matters: each then gets its own, on a new branch.
A tree in the sidebar
With tabs on the left, workers sit under the session that started them, joined by a line, without taking you away from the tab you're on. ⌘1 to ⌘9 still count straight down the column. Drag a worker elsewhere and it's a tab like any other.
Asks first
Claude Code asks you before a worker starts, gets a message or is stopped, as for any tool, unless you've chosen to allow it or run in a mode that skips asking. A worker doesn't inherit its parent's permission mode, so its own prompts come to you.
Kept in bounds
A session reaches only the workers it started, on its own Claude account. Workers can't start workers, and at most five of a session's can be busy at once. Each one uses your plan like any other session.
Merging is yours
A worker's work stays on its branch. Claude can propose merging it, and the decision is yours.
Closing them
Closing a session closes its workers once they've finished and nothing would be lost. If one is still running or holds uncommitted or unmerged work, Titan asks: Keep Workers or Close All, which deletes that work. Closing a worker on its own removes its worktree and branch, asking first if that would lose uncommitted files or commits not merged. A squash merge counts as not merged, since git can't see it.
Turning them off
Settings › Agents › Run workers, or orchestration = false, for sessions started after that. Claude then tells you they're off if you ask for them.
Workers as cards
Each worker shows as a card in the conversation that started it, where it was started: its status, what it's at and who started it. Click it to open its tab. A turn that only starts workers or takes their reports shows just the cards. New in 0.27.
Recurring checks
Ask a session to do something regularly, “check the nightly build every hour and fix what broke”, and it sets up a schedule, asking you first. Titan sends it a marked message each time and it decides which workers to start. Runs are at least 15 minutes apart, five at most per session, and each costs a turn. A Recurring checks strip over the session lists them, with when each runs next and Stop; worker-ledger = false (Settings › Agents › Worker summary) hides it. While Titan is closed none run; one catches up when you open it. New in 0.27.
Results arrive whole
A worker's report carries its whole last reply, up to 30,000 characters, so the session doesn't have to go looking for the rest.
After a restart
Workers carry on while Titan is closed, and a report still owed arrives when you open it again, waking the session that's owed it. A worker whose process was lost, to a Mac restart say, reports that its work may be unfinished. New in 0.25.

Sharing

New in 0.20.

Send a teammate a session, and let them carry on from it. It stays a file you send: nothing is uploaded, and there's no account or server involved.

Share Conversation…
In the palette, or Export in the session's menu. It makes a copy with tool output and Claude's thinking left out, and secrets, email addresses, your home folder and your login hidden, without the session's id or full path. It opens in a preview you can edit, and Save… or Copy uses what's in the preview.
Read it before it goes
Cleaning only recognises common shapes. Names, clients, internal hostnames and a password written in a sentence stay in, and code you pasted stays as it was. Once a file is sent, Titan can't take it back.
Continue from Shared Copy…
In the palette, on the other side: pick the file, then your checkout of the project. A new session opens with a line saying where it came from and a message in its input, for you to read and send. Any other file is refused.
What carries over
The decisions and reasoning, not tool output or the original session's memory, so Claude runs again what it needs. It's told the copy is a record to use as information, not instructions to follow, and to check it against the code.

Spaces experimental

New in 0.27.

A Space is where a small team works together: a goal, the people in it, and an agent that turns their requests into workers, with comments on the conversation. Spaces live on a server your team runs; set spaces-server = https://… and they appear in the sidebar, above your projects.

A Space and its agent
+ in the sidebar's SPACES section makes one: a name, a goal and the git repository its agent works in. The agent is a Claude session in a worktree of that repository, on a branch of its own, space/<name>. Its tab is the Space's chat, with the Space beside it: the goal, who's in it, its threads and comments.
Sandboxed
Teammates' messages reach the agent without anyone approving them, so it runs inside Anthropic's sandbox runtime (npm install -g @anthropic-ai/sandbox-runtime). It can read and write its worktree and commit on its own branch, never main; it reaches Anthropic and the hosts you allow; and it can't read the rest of your home folder, your other conversations or your Keychain. Merging and pushing stay yours.
Teammates
Only the owner invites. A teammate opens the Space as a tab like the owner's and writes to the agent with Message the Space…; the message reaches the owner's Titan marked as theirs, never as if the owner typed it, and waits while the owner's Titan is away.
Comments
Hover a message in a Space's conversation and click the speech bubble to comment: replies, reactions and attached files, in a panel over the side of the conversation. Back after a while, a few lines at the end say what happened since.
Assigning
Right-click a thread or a worker's card for Assign To, and the agent can assign by name too. New in 0.28.

The terminal

libghostty inside
The same VT core as Ghostty, drawn with Metal. Improvements upstream arrive as a rebuild, not a rewrite.
Sessions outlive the window
Shells and Claude sessions run in titan-ptyd, a small daemon, so quitting or updating Titan doesn't stop them. Reopen it and they're where you left them.
Tabs and splits
⌘D and ⇧⌘D split, ⇧⌘↩ expands a pane, and a grip shows on the divider as you drag it. Drag panes onto tabs, tabs out into windows. ⌘E shows every tab and its panes.
Cursor trails
cursor-trail animates the cursor as it moves: smear stretches it and lets it catch up, comet leaves a fading tail, ripple sends a ring out after a jump. Smear is the default, unless you use custom shaders; none turns it off.
Float a pane
The float button in a pane's header, or Float Pane in the palette, lifts it into a card over its window: drag its header to move it, its edges to resize it. – shrinks it to a pill in the bottom right corner, with a dot while Claude works or waits on you; click to open it again. Its session keeps running, and Put Pane Back returns it to its tab.
Recipes
Saved setups of shells and a browser in the config. They ask for what they need, a branch or a port, then open everything beside the pane you're in.
Images in the shell
The Kitty graphics protocol: kitty icat, yazi and ranger previews, chafa, image.nvim. titan diagram draws a Mermaid file right in the shell.
What's still running
A dev server an agent backgrounded, a nohup from a pane you closed: Running in Background finds them, with their ports, and stops them.
More than one Claude account
Map folders to Claude accounts and each session opens under the right one, its history kept apart. Continue a session under the other account in one click.

The browser

The Web Inspector and signing in are new in 0.17.

A browser pane sits beside your work, for pages you and your agents are working on. ⇧⌘B opens one and ⌘L goes to its address. Web links from shells and conversations open in it, unless links-in-titan = false.

Web Inspector
The wrench in the pane's bar, ⇧⌘I, or Inspect Element in a page's context menu docks WebKit's inspector in the pane: elements, console, network, sources and storage. Agents have no tool for it, and nothing outside Titan can attach to your pages.
Sign-in pages wait for your click
By default a pane doesn't sign in to anything but a local server. A sign-in page (Google, Microsoft, Okta, GitHub, /login and OAuth pages) or a page asking for a password isn't shown: the pane offers a button to open it in your default browser. Nothing opens until you click it, and neither a page's script nor an agent can press it.
Or sign in to your own panes
browser-sign-in = true, off by default, lets your own panes sign in and stay signed in. Their cookies are saved encrypted, with the key in your Keychain, so an agent with a shell can't read them from disk. Local storage isn't saved, so a site that keeps its login there signs out when Titan quits. Turn it off and what was saved is deleted at the next launch.
Agents stay out
Agents' panes never sign in and keep their cookies in memory, apart from yours. Their tools can't reach your panes, and titan panes hides those panes' addresses and titles from them.
Frames and whole pages
Agents read and use iframes of any origin, such as an embedded form or checkout, and can screenshot a whole page without scrolling the one you're watching. New in 0.23.
When a site won't have it
A pane has no password manager and limited passkey support, and some providers refuse embedded browsers. The Safari button in the bar opens the page in your default browser.

Benji

New in 0.12.

Titan's assistant: a Claude conversation in a window of its own, opened with ⌃/, View → Benji, or the little Benji in the sidebar.

Runs sessions for you
Starts Claude sessions in your projects, each in a tab of its own, gives them tasks and more instructions, reads what they did, stops them, and reports back; several at once when a request splits.
Knows Titan
Answers how-to questions from Titan's manual and changelog, and runs Titan's commands for you. It needs no remote-control.
Conversations of its own
Each named in a few words, kept between launches, archived once inactive for 72 hours.
Its account and model
Settings › Claude Pane › Benji picks the Claude account it runs as (the first claude-account unless you choose) and its model: Haiku by default, so it's quick, or Sonnet or Opus. Or benji-account and benji-model in the config. A conversation stays on the account it began on. New in 0.15.

Worktrees

A git worktree is a second working folder of the same repository, on a branch of its own. With agents it lets two sessions, or you and a session, change one repository at the same time without mixing each other's edits, tests or commits.

Start one
A session works directly in its folder unless you ask. New Worktree in the folder chip of the ⌘N box gives it a checkout of its own, or press ⇧⌘N, then type a new branch name (made from the remote's default branch) or pick an existing branch. Claude starts in <repo>.worktrees/<branch>, beside the repository. Review and merge its branch when it's done, like a teammate's.
One that already exists
⌘O, then its folder, or pick it by branch in the folder chip of the ⌘N box. The session works there from the start.
From a session started elsewhere
A session can work in a worktree of the same repository without starting there, but Claude has to name it in each command, since Claude Code doesn't let a cd outside the session's folders carry over. The folder and branch above the input, the status card, /diff and the +/− chip follow the worktree it's working in. That's a best guess from where Claude last worked, so run git status there before committing. New in 0.20.
Running the project
A worktree is a separate folder with its own files, so start a dev server from inside it, or you're testing whatever branch the main folder is on. Two dev servers may want the same port.
Asked when a checkout is taken
Off by default. With worktree-offer = true, starting a session in a repository where another Claude session is already open asks first: In a Worktree… or Here.
Closing the session
The worktree folder goes, and the branch stays with what's committed on it. Titan asks first if the folder holds uncommitted changes, or files git ignores that exist nowhere else, like a copied .env you edited, and names them. What's the same in the main checkout and what a build makes (node_modules, .build, dist and the like) go without asking.
What a worktree is missing
Only what git tracks. What the repository ignores, like .env, node_modules or built libraries, isn't there, so the project often won't run in a new worktree.
.worktreeinclude
List those paths in a .worktreeinclude file at the top of the repository, one per line, and every new worktree brings them in from the main checkout. A folder is linked (shared, instant, no extra space), a file copied (the worktree's own). Write link or copy before a path to choose. The session's feed says what came in. Commit the file for your team, or keep it out of git just for you.
Or in the config
For a repository you'd rather not add a file to: worktree-include = ~/code/app: .env, node_modules.
Kept safe
Only paths inside the repository that git ignores are brought in: nothing with .., ~ or .git, and no link that leads outside it. Links are added to git's exclude list, so they never show in git status or get committed, and closing the session removes the links, never what they point to.
.worktreeinclude
# What git ignores that a worktree needs
.env
.env.local
node_modules
copy build

Profiles

New in 0.15.

A profile is a set of settings laid over your config while it's on. Turning it off puts everything back as it was: your config itself is never rewritten.

Switch one on
The Profile row on Settings › Appearance (the one on is highlighted), View › Profile, or Switch Profile in the palette. None turns it off. The config gets one line, profile = Presenting.
Titan's five
Minimal, a plain terminal. Agent-heavy, several sessions at once with their status down the left and the Mac kept awake. Keyboard-first, files in your editor and a block cursor. Presenting, larger text and strong contrast for a demo or a shared screen. Focus, no animations or long-command notifications.
Your own
New asks for a name, then writes ~/.config/titan/profiles/<Name>.conf listing every setting a profile can have, commented out with the value you have now, opens it in your editor and turns it on. Take the # off the lines you want and change them: each shows as you save. Edit File opens any profile's file, Titan's included; Reset to Titan's undoes your changes to one of those.
Changing one while it's on
Settings it sets say so in their rows, and changing one there saves it to the profile, where it takes effect.
What a profile can't set
Remote control, Claude accounts, hosts, recipes and keybinds stay as your config has them, whichever profile is on.
~/.config/titan/profiles/Pairing.conf
# Big and clear for pairing or a call
theme = TokyoNight Day
font-size = 20
adjust-cell-height = 12%
minimum-contrast = 4.5
reading-width = 72
notify-after = 0
agent-background = dots

Hooks new

New in 0.33.

A hook runs a command of yours when something happens in Titan: one line in the config each, any language, and titan do to act back on the pane it came from.

~/.config/titan/config
hook = agent-turn-done, ~/bin/reload-nvim.sh
hook = command-exit, ~/bin/on-fail.sh
command-exit
A shell command ended: TITAN_COMMAND, TITAN_EXIT_CODE, TITAN_DURATION in seconds.
cwd-changed
A shell moved to another folder: TITAN_OLD_CWD.
agent-turn-done
A Claude turn ended: TITAN_STATUS (finished or failed), TITAN_REPLY, TITAN_FILES (the files the turn wrote, one per line), TITAN_DURATION.
agent-waiting
Claude asks for an allow or deny: TITAN_TOOL, TITAN_REQUEST.
worker-done
A worker's job ended: TITAN_STATUS (finished, failed or interrupted), TITAN_REPLY, and TITAN_PARENT, the session that started it.
open-file
A path was clicked in a shell or a reply: TITAN_FILE, TITAN_LINE, TITAN_REPO. A hook that exits 0 within 2 seconds has opened it, and Titan leaves it; otherwise Titan opens it as usual.
project-opened
A shell or Claude session started in a git repository nothing else had open: TITAN_PROJECT, TITAN_KIND. Titan reopening its sessions doesn't count.
What every hook gets
TITAN_EVENT, TITAN_CWD (where it happened, and where the hook runs), and TITAN_PANE, so titan do acts on that pane (with remote-control on). It runs with /bin/sh, your shell's PATH and Titan's own titan first on it, in the background, a minute at most. Each run's output goes to hooks.log in Titan's support folder. titan do focus_pane pane=ID brings a pane forward.
~/bin/reload-nvim.sh: Neovim picks up what Claude changed
#!/bin/sh
sock="/tmp/nvim-$(basename "$TITAN_CWD").sock"     # nvim --listen that path
[ -S "$sock" ] && nvim --server "$sock" --remote-expr 'execute("checktime")'

Lua plugins new

New in 0.33.

Plugins are Lua 5.4: ~/.config/titan/init.lua, then every file in ~/.config/titan/plugins by name. They load at launch and again as soon as one changes. A plugin hears the same events as hooks, inside Titan, so it can answer at once; it runs Titan's actions, adds palette commands and talks to the Neovim running in a pane, however it was started.

~/.config/titan/init.lua
-- Claude changed files: Neovims in that repository reload them.
titan.on("agent-turn-done", function(ev)
  for _, nv in ipairs(titan.nvim_panes{ cwd = ev.cwd }) do nv:cmd("checktime") end
end)

-- A clicked path opens in the Neovim already running, which comes forward.
titan.on("open-file", function(ev)
  local nv = titan.nvim_panes{ cwd = ev.repo }[1]
  if not nv then return false end        -- none: Titan opens it
  nv:edit(ev.file, ev.line)
  nv:focus()
  return true
end)

-- A palette command (⌘P).
titan.palette("Tests beside", function()
  titan.run("new_split", { direction = "down", command = "npm test" })
end)
titan.on(event, fn)
fn(ev) when it happens: the hooks' events, their fields as Lua values (ev.exit_code, ev.cwd, ev.pane, ev.files as a list). An open-file handler that returns true has opened the file.
titan.run(action, args, fn)
Any action as titan do runs it, {pane = id} to act on that pane; fn(result) hears the answer. Plugins are your own code, like your shell scripts, so this works with remote-control on or off.
titan.panes(), titan.palette(name, fn), titan.notify(text), titan.shell(cmd)
Every pane; a command in the palette; a notification; a command run with /bin/sh, its output and exit status. print writes to hooks.log.
titan.nvim(pane), titan.nvim_panes{cwd = dir}
The Neovim in a pane, found by its process, with or without --listen. nv:edit(path, line), nv:cmd(":cmd") in any mode, nv:eval(expr), nv:lua(code) and nv:focus().
It can't hang Titan
Loading a file may take five seconds and an event's handlers two; past that Titan stops the plugin, and a pcall doesn't get round it. Errors show with their file and line in the bar at the bottom of the window.

Actions

Every command in Titan is a named action. Bind it to a key, run it from a shell with titan do, or let an agent run it. Pick an action to see each way to call it, and what Titan answers.

    zsh · titan do
    
                

    Needs remote-control = true in the config, except titan browser. titan actions lists every action, titan panes what's open.

    Pane limits

    An agent can use the panes it opened and the ones you grant it. For any other shell, Titan asks you first, so an agent that was talked into it can't type into your ssh session or a shell with sudo still warm. Pick a mode, then have pi type into each pane.

    remote-control =
    π pi~/code/pomodoro · the agent

    Click a pane to have pi type into it.

    Its own browser, and only that
    An agent drives the browser pane beside the pane it runs in, not another conversation's.
    Never signed in
    An agent's browser pane doesn't sign in to anything but a local server, and its cookies and storage are gone when Titan quits. A sign-in page shows a button for you to open it in your own browser, which only your click can press, so nothing in a pane can send an address to the browser you're signed in to. See The browser.
    Known by where it started
    Titan reads which pane an agent belongs to from the agent's own process, not from what a request claims, so pointing TITAN_PANE at another pane gains nothing.
    A log of what it did
    A pane an agent types into or reads shows a badge for a moment, and Show Remote Control Log lists the last 200 requests: who, what, which pane, and what you said.

    Config

    Same syntax as Ghostty's: key = value, one per line. Anything you leave out keeps its default. Build a starting file here and copy it into ~/.config/titan/config. To switch several settings at once, use a profile.

    start from
    Look
    Claude pane
    Agents
    Extras
    ~/.config/titan/config
    
                

    Keys

    The defaults. Every one can be rebound, removed or turned into a sequence with keybind, and the menus show the new key as soon as you save. In Titan, ⌘/ lists every key in effect, your own included.

    FAQ

    Can I use pi or Codex instead of Claude?
    Yes. Run them in a Titan shell. They drive Titan with the titan command (titan do, titan panes, titan browser), and Titan keeps them to their own panes as it does Claude. The Claude pane itself is for Claude Code.
    Can agents type into my shells?
    Not without asking. They can use the panes they open themselves and the ones you grant; for any other shell, Titan asks you first, and you can allow it once or for that pane. It's all off until you set remote-control = true.
    Can agents use my logins?
    Not through Titan's browser. Agents' browser panes never sign in. If you turn on browser-sign-in for your own panes, agents' tools can't reach those panes and their saved cookies are encrypted, with the key in your Keychain. An agent with a shell runs as you, though, so it can still do what your user can, like opening a link in your default browser; keep that in mind when you allow its commands. See The browser.
    Can I script Titan?
    Yes, three ways. titan do runs any action from a shell or an agent; hooks run a command of yours when something happens; Lua plugins do both inside Titan, and reach the Neovim in your panes.
    Does it need an API key?
    No. Titan runs the Claude Code that's installed, so sessions use the account it's signed in with and count against that plan as usual. pi and other agents use whatever they're set up with.
    Does it change how Claude Code behaves?
    Barely. It's the same CLI with your settings, skills and MCP servers. Titan adds a short note to the system prompt so Claude knows that pages show up in the feed, how to write paths that link, where Titan's manual is, and, when you turn it on, that it can open panes. It also gives Claude tools of its own: the browser, reading other sessions and running workers, the last two of which session-tools and orchestration turn off.
    Where are my conversations?
    Where Claude Code keeps them, in ~/.claude/projects. Titan reads them for its history list and to resume sessions, and they work in the plain claude TUI as well.
    Why only macOS?
    Titan is a native Mac app: SwiftUI and AppKit for the window, Metal for drawing, Liquid Glass from macOS 26. Its terminal core, libghostty, runs elsewhere, but everything around it is written for the Mac. There are no plans for Linux or Windows.
    Where do I send feedback?
    Titan is a personal project and I'd like to hear what you think. Open an issue on the releases repo: what works, what doesn't, what you'd want next.