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
- 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). - 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. - 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.
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.
pomodoro ❯ claude ╭──────────────────────────────────────╮ │ ✻ Welcome to Claude Code │ ╰──────────────────────────────────────╯ mcp: titan · browser_*, titan_do, titan_panes > open the timer in the browser beside me
Prefer the TUI? Type claude
In a Titan shell, claude starts with Titan's hooks and tools added for that run only, never written to your settings. The tab shows when it's working or waiting, the Mac stays awake while it works, and it gets the browser and titan_do tools.
With several Claude accounts, the folder picks the account, or claude --account Work does.
pomodoro ❯ pi Start the dev server beside you with titan, open it in the titan browser and click Break. $ titan do new_split direction=right command="npm run dev" $ titan browser navigate url=http://localhost:4173/ $ titan browser click ref=e3 Done.
pi works as it is
pi needs no plugin and no MCP setup. In a Titan shell it runs titan do, titan panes and titan browser with its bash tool, and finds them from titan actions. Its status shows on the tab from the escapes pi already sends.
Titan knows pi when it sees it, even renamed to pi by node, and keeps it to the panes it opened.
pomodoro ❯ codex $ titan actions new_split direction=right|down [command=CMD] [folder=DIR] read_pane pane=ID [lines=N] titan browser <tool>: navigate, snapshot, click, type…
Codex, OpenCode, Gemini, Aider…
Any agent that can run a shell command can drive Titan the same way. Titan recognises Codex, OpenCode, Gemini, Aider, Amp, Goose, Crush and Cursor's agent by their process, or by AI_AGENT in their environment, and gives them the same pane limits as Claude.
| Claude pane | claude in a shell | pi, 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 TUI | its 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
$ cmdtranscript without the prompts. Copy on every block new in 0.29. - See what changed
/diffopens 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_findsearches titles, folders and content,session_grepsearches one session, andsession_readreads 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_outputshows 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
mermaidblock 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-253findsfeature/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 = falsehides 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 = trueadds 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/prand only reads with them.- Ask Claude about a pull request
- The Review pane that
/propens 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/repoin 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
/costor/usagedraws 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(oruninstall,enable,disable) changes Claude Code's plugins and reloads them in the same conversation;/pluginalone 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 = trueputs 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
cleanupPeriodDaysin that account'ssettings.json(30 days by default). New in 0.22.
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-aheadpercent 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 = 0leaves 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.
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, nevermain; 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-trailanimates the cursor as it moves:smearstretches it and lets it catch up,cometleaves a fading tail,ripplesends a ring out after a jump. Smear is the default, unless you use custom shaders;noneturns 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 diagramdraws a Mermaid file right in the shell. - What's still running
- A dev server an agent backgrounded, a
nohupfrom 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,
/loginand 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 paneshides 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-accountunless you choose) and its model: Haiku by default, so it's quick, or Sonnet or Opus. Orbenji-accountandbenji-modelin 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
cdoutside the session's folders carry over. The folder and branch above the input, the status card,/diffand the +/− chip follow the worktree it's working in. That's a best guess from where Claude last worked, so rungit statusthere 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
.envyou edited, and names them. What's the same in the main checkout and what a build makes (node_modules,.build,distand the like) go without asking. - What a worktree is missing
- Only what git tracks. What the repository ignores, like
.env,node_modulesor built libraries, isn't there, so the project often won't run in a new worktree. .worktreeinclude- List those paths in a
.worktreeincludefile 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). Writelinkorcopybefore 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 ingit statusor get committed, and closing the session removes the links, never what they point to.
# 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>.conflisting 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.
# 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.
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_DURATIONin seconds. cwd-changed- A shell moved to another folder:
TITAN_OLD_CWD. agent-turn-done- A Claude turn ended:
TITAN_STATUS(finishedorfailed),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,failedorinterrupted),TITAN_REPLY, andTITAN_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), andTITAN_PANE, sotitan doacts on that pane (withremote-controlon). It runs with/bin/sh, your shell's PATH and Titan's owntitanfirst on it, in the background, a minute at most. Each run's output goes tohooks.login Titan's support folder.titan do focus_pane pane=IDbrings a pane forward.
#!/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.
-- 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.filesas a list). Anopen-filehandler that returnstruehas opened the file.titan.run(action, args, fn)- Any action as
titan doruns 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 withremote-controlon 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.printwrites tohooks.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)andnv: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
pcalldoesn'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.
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.
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_PANEat 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.
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
titancommand (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-infor 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 doruns 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-toolsandorchestrationturn 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 plainclaudeTUI 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.