Turnlane

Practical guide · Claude Code + Codex

Which AI coding agent needs you next?

When two or three agents are running, checking every tab becomes another job. Use Turnlane’s Your turn queue to see what needs a reply, approval, or review—and return to the work.

For macOS 14 or later · Apple Silicon · Free and open source

Set up Turnlane · Use Your turn · Understand notifications

Turnlane’s Your turn queue, with waiting items and the selected item’s timeline.
Example screen with synthetic data. Your turn brings different kinds of waiting work together.

Start with the reason for the wait

You leave one agent refactoring, another investigating a bug, and switch to your own work. When you return, one needs permission, another has asked a question, and a third has changes to review. A notification can draw your attention; the queue tells you what still needs it.

  1. Open Your turn. Look at the item’s title, repository, waiting reason, and elapsed waiting time. The board also places AI work beside your tasks and calendar.
  2. Read the item before acting. Open its detail to see the available context. A permission request, a question, a PR review, and an error need different responses.
  3. Choose Open and respond. For a supported live terminal session, this brings its existing tab forward. Answer there, or use Answer in Turnlane where supported. Turnlane only sends what you explicitly submit; it does not decide an answer or approve work for you.
  4. Leave what can wait for later. Snooze an item, or mark it handled or not needed when appropriate. Items also close when Turnlane detects that the agent has moved on.

For Codex, returning to the live tab and answering from Turnlane require hooks. Terminal support also matters: tmux, Terminal, iTerm2, Ghostty 1.3 or later, and Orca have supported paths. Warp and Kitty require tmux for Answer. Sessions in desktop apps can be imported, but Answer cannot send into their chat views. You can always inspect the original session yourself.

Try it with the agents you already run

You need an Apple Silicon Mac running macOS 14 or later and local Claude Code or Codex sessions. No Turnlane account is needed.

1. Install and open Turnlane

Unzip the download, move Turnlane to Applications, and open it. Or install with Homebrew:

brew install --cask turnlane/tap/turnlane

2. Choose what to import

In first-run setup, select your agents’ record folders and consent to importing them. Turnlane imports the last seven days of work. Calendar access and notifications are optional; you can try the AI queue without connecting a calendar.

Claude Desktop’s Code tab and the Codex desktop app can use the same local records. Web chats, Claude’s ordinary chat view, and ChatGPT chats are not imported.

3. Add hooks for timely signals

Install Turnlane’s hooks during setup, or use the CLI:

turnlane hooks install

If you installed from the zip, first install the command-line tool from setup or Settings → General. Homebrew puts it on your PATH. Restart running Claude Code and Codex sessions after installing hooks. In Codex, run /hooks and approve Turnlane’s entries.

Hooks are optional for importing and showing work. Without them, waits are inferred from local records and can take roughly a minute to appear. Codex also needs hooks to identify its live process for Open and respond and Answer. To remove Turnlane’s hooks, use turnlane hooks uninstall.

4. Check one real handoff

Continue your normal work. When an agent next asks for input or leaves a result to review, check its row and waiting reason in Your turn. Follow Open and respond if available. There is no need to create a permission request just to test the queue.

A visible row is not an instant notification

Your turn is the name of the queue. Internally, a blocked permission or input request is needs_input; a finished turn awaiting a reply or review is your_turn. Errors can also produce an item in the queue.

  • Blocked requests: hooks provide timely signals. Permission notifications wait 10 seconds so a request that resolves quickly does not need to interrupt you.
  • A turn ending with a question: while you are at your Mac, the default grace period is 15 minutes. A faint row appears during that period and is not included in the queue count; it becomes a regular row after it. You can change the grace period in Settings. If you were away when the turn ended, that grace period is skipped.
  • Notifications: new blocked or error items use the immediate path; other Your turn items are batched on a 15-minute cadence. The question grace period and this notification cadence are separate.

Keep the Turnlane desktop app running and enable notifications in macOS if you want banners. Turnlane’s Focus mode holds notifications for a summary when focus ends, with an option to let blocked requests through. macOS settings can suppress banners. The same item is not notified again within five minutes, and the initial import does not send a backlog of alerts. Use the queue to check current waiting work; it is not a notification-history archive.

The time on a row shows how long the item has been waiting. The day’s record separately shows Idle: the part of that wait while you were at your Mac, excluding away time and calendar busy time.

What Turnlane reads and keeps

Turnlane reads local Claude Code and Codex records and optional hooks. It stores work metadata such as timestamps, repository, branch, and state. It can also keep bounded, best-effort-masked details: the first line of your instruction, the agent’s question and options, the requested tool and command or path, and the error kind. You can disable or delete these saved details in Settings → Data.

It does not copy entire session logs, diffs, or file contents into its database. The agent’s last reply is read from the local log when you open the detail, shown as an excerpt of up to 2,000 characters, and not stored. There is no Turnlane account, cloud sync, or telemetry. Update checks and downloads use GitHub Releases and can be disabled. Optional features that call your own AI tools or expose data through MCP have their own data paths; see the privacy details before enabling them.

If the first item does not look right

  • No work appears: check that you selected the record folder used by the agent you are running and allowed the import.
  • A question looks faint: it may still be in its grace period. A missing banner does not mean there is no waiting work.
  • Codex will not open or accept an answer: check that hooks are installed, approved in /hooks, and active after restarting the session.
  • The row does not match the conversation: classification from records is not perfect. Check the original session and mark the item handled or not needed as appropriate.

Start with one normal handoff and decide whether having it beside your day’s work helps. Return to installation and setup, or explore the Turnlane overview.