Introduction

Conduit is a multi-agent terminal user interface (TUI) that lets you run AI coding assistants side-by-side. Orchestrate Claude Code and Codex CLI in a tabbed interface with full session management, git integration, and real-time token tracking.

Key Features

• Multi-Agent Tabs — Run up to 10 concurrent AI sessions in tabs, switch instantly with Alt+1-9
• Session Persistence — All conversations are saved and can be resumed later
• Git Integration — Automatic worktree management, branch status, and PR tracking
• Build & Plan Modes — Toggle between full execution and read-only analysis
• Customizable — Configure keybindings, themes, and tool paths
• Token Tracking — Real-time usage and cost estimation in the status bar

Supported Agents

Quick Example

# Start Conduit
conduit

# In the TUI:
# Ctrl+N    → Open project picker
# Enter     → Select a repository
# Type      → Send prompts to the agent
# Alt+2     → Open a second tab
# Ctrl+Q    → Quit

Getting Started

1. Install Conduit
2. Quick Start Guide
3. Your First Session

Requirements

• Git — Required for workspace management
• At least one agent — Claude Code, Codex CLI, or Gemini CLI installed and configured
• Terminal — A terminal emulator with good Unicode and color support

Navigation

Use the sidebar to browse documentation by topic, or use the search (/ or s) to find specific information.

Conduit is currently in early access. Join our Discord for support and updates.

Installation

Quick Install

The fastest way to install Conduit:

curl -fsSL https://getconduit.sh/install | sh

This script automatically detects your platform (macOS/Linux) and architecture, downloads the appropriate binary, and installs it to ~/.local/bin.

Prerequisites

Before using Conduit, ensure you have:

• Git — Required for workspace and worktree management
• At least one AI agent:
  • Claude Code — npm install -g @anthropic-ai/claude-code
  • Codex CLI — npm install -g @openai/codex
  • Gemini CLI — npm install -g @google/gemini-cli

Alternative Installation Methods

Homebrew (macOS/Linux)

brew install conduit-cli/tap/conduit

Cargo (from crates.io)

cargo install conduit-tui

Build from Source

Clone the repository and build with Cargo:

git clone https://github.com/conduit-cli/conduit.git
cd conduit
cargo build --release

The binary will be at ./target/release/conduit.

Add to PATH

# Copy to a directory in your PATH
cp ./target/release/conduit ~/.local/bin/

# Or create a symlink
ln -s $(pwd)/target/release/conduit ~/.local/bin/conduit

Verify Installation

# Check Conduit is installed
conduit --version

# Start the TUI
conduit

First Run

On first launch, Conduit will:

1. Detect Git — Shows an error dialog if Git is not found
2. Detect Agents — Searches for claude, codex, and gemini binaries
3. Create Config Directory — Creates ~/.conduit/ for settings and data

If no agents are found, you’ll be prompted to configure tool paths in the settings.

Directory Structure

Conduit stores its data in ~/.conduit/:

~/.conduit/
├── config.toml      # Configuration file
├── conduit.db       # SQLite database (sessions, workspaces)
├── logs/            # Application logs
├── workspaces/      # Workspace data
└── themes/          # Custom theme files

Next Steps

• Quick Start — Get up and running in 5 minutes
• Configuration — Customize Conduit

Quick Start

Get up and running with Conduit in 5 minutes.

Start Conduit

conduit

You’ll see the main interface with a sidebar on the left and an empty chat area.

Open a Project

1. Press Ctrl+N to open the project picker
2. Type to filter your recent repositories
3. Press Enter to select one, or Ctrl+A to add a new repository

A new tab opens with your project loaded.

Send a Prompt

1. Type your message in the input box at the bottom
2. Press Enter to send
3. Watch the agent work — you’ll see tool executions and responses in real-time

Essential Shortcuts

Open Multiple Tabs

Run multiple agents simultaneously:

1. Press Ctrl+N to open another project
2. Use Alt+1, Alt+2, etc. to switch between tabs
3. Or use Alt+Tab / Alt+Shift+Tab to cycle through

Each tab runs independently — you can have Claude working on one task while Codex handles another.

Toggle Build/Plan Mode

Press Tab to switch between:

• Build Mode (default) — Agent can read, write, and execute commands
• Plan Mode — Read-only analysis, no modifications

The status bar shows the current mode.

Plan mode relies on prompt guidance for Codex and Gemini, so treat it as best-effort.

View Token Usage

The status bar displays:

• Input/output token counts
• Estimated cost
• Current model

Toggle the display in settings or with Alt+P.

Next Steps

• First Session — A detailed walkthrough
• Keyboard Shortcuts — Full shortcut reference
• Configuration — Customize your setup

First Session

A detailed walkthrough of your first Conduit session.

Launch and Initial Setup

Start Conduit from your terminal:

conduit

The Interface

You’ll see:

• Sidebar (left) — Projects and workspaces tree
• Tab Bar (top) — Open sessions
• Chat Area (center) — Conversation with the agent
• Input Box (bottom) — Where you type prompts
• Status Bar (bottom) — Token usage, mode, branch info

First-Time Detection

On first run, Conduit checks for:

1. Git — Required for all operations
2. Agents — Looks for claude, codex, and gemini in your PATH

If an agent isn’t found, you can configure its path in settings (s from sidebar).

Creating Your First Project

Open the Project Picker

Press Ctrl+N. The picker shows:

• Recent repositories you’ve worked with
• Fuzzy search as you type
• Option to add a new repository

Select or Add a Repository

For an existing repo:

• Type to filter the list
• Use Ctrl+K / Ctrl+J to navigate
• Press Enter to select

To add a new repo:

• Press Ctrl+A
• Enter the path to your repository
• The repo is added to your projects

Workspace Creation

When you select a project, Conduit creates a workspace tied to your current git branch. This workspace stores:

• Session history
• Branch association
• Metadata

Interacting with the Agent

Send Your First Prompt

Type a message and press Enter:

What files are in this project?

The agent will:

1. Analyze your request
2. Execute tools (file reads, searches, etc.)
3. Stream the response to you

Understanding the Response

You’ll see:

• Tool Calls — Commands the agent executes (file reads, writes, bash commands)
• Thinking — The agent’s reasoning (if visible)
• Response — The final answer

Follow-Up Questions

Continue the conversation naturally:

Can you explain how the main function works?

The agent maintains context from previous messages.

Managing Your Session

Scroll Through History

• Page Up / Page Down — Scroll the chat
• g / G — Jump to top/bottom (in scroll mode)
• Esc — Return to the bottom

Interrupt the Agent

If an agent is taking too long:

• Press Ctrl+C once to clear the input
• Press Ctrl+C twice quickly to interrupt the agent

Switch Modes

Press Tab to toggle between:

• Build Mode — Full capabilities
• Plan Mode — Read-only analysis

Plan mode is enforced by Claude Code; for Codex and Gemini it’s a best-effort prompt reminder.

Saving and Resuming

Automatic Saving

Sessions are automatically saved to the database. When you close Conduit, your conversation is preserved.

Resume a Session

1. Open Conduit
2. Navigate to your project in the sidebar
3. Select the workspace — your session continues where you left off

Import External Sessions

Press Alt+I to import sessions from:

• Claude Code sessions (from ~/.claude/)
• Codex sessions

Closing Up

Close a Tab

Press Alt+Shift+W to close the current tab.

Quit Conduit

Press Ctrl+Q to exit. Your session is automatically saved.

Tips for Effective Sessions

1. Be specific — Clear prompts get better results
2. Use Plan mode first — Analyze before making changes
3. Check the status bar — Monitor token usage and costs
4. Multiple tabs — Run different tasks in parallel
5. Use the command palette — Ctrl+P for quick access to actions

Next Steps

• Core Concepts — Understand projects, workspaces, sessions
• Keyboard Shortcuts — Master the interface
• Configuration — Customize your experience

Projects

A project in Conduit represents a git repository you work with.

What is a Project?

• A project is tied to a specific git repository
• Projects contain one or more workspaces
• Each workspace corresponds to a git branch

Adding Projects

1. Press Ctrl+N to open the project picker
2. Press Ctrl+A to add a new repository
3. Enter the path to your git repository

Project Tree

The sidebar displays your projects in a tree structure:

Project Name
├── main (workspace)
├── feature-branch (workspace)
└── bugfix (workspace)

Managing Projects

From the sidebar:

• r — Add a new repository
• x — Archive or remove a project
• s — Open settings

Workspaces

A workspace is a working context within a project, tied to a git branch.

What is a Workspace?

• Each workspace corresponds to a git branch
• Workspaces use git worktrees for isolation
• Session history is stored per workspace

Git Worktrees

Conduit automatically creates git worktrees for each workspace. This allows:

• Working on multiple branches simultaneously
• Independent file states per branch
• Clean separation between features

Creating Workspaces

When you open a project on a new branch, Conduit creates a workspace automatically.

Workspace Storage

Workspace data is stored in:

~/.conduit/workspaces/<project>/<branch>/

Archiving Workspaces

Press x on a workspace in the sidebar to archive it. This:

• Removes it from the sidebar
• Preserves session history
• Cleans up the worktree

Sessions

A session is a conversation thread with an AI agent.

What is a Session?

• Sessions contain the full conversation history
• Each tab has one active session
• Sessions are persisted to the database

Session Persistence

All sessions are automatically saved to ~/.conduit/conduit.db. You can:

• Close Conduit and resume later
• Switch between workspaces
• Import external sessions

Session History

The session maintains:

• All messages (prompts and responses)
• Tool executions and outputs
• Token usage statistics
• Timestamps

Resuming Sessions

When you open a workspace, the previous session continues automatically.

Importing Sessions

Press Alt+I to import sessions from:

• Claude Code (~/.claude/)
• Codex CLI

Use Tab to filter by agent type.

Tabs

Run multiple AI sessions simultaneously with tabs.

Multi-Tab Interface

• Run up to 10 concurrent sessions
• Each tab is independent
• Switch instantly between contexts

Tab Shortcuts

Tab Indicators

The tab bar shows:

• Session name / branch
• Agent status (idle, running, thinking)
• PR status (if applicable)
• Git status indicators

Parallel Workflows

Use tabs to:

• Run different agents on separate tasks
• Compare approaches side-by-side
• Keep reference conversations open

Agents

Conduit orchestrates AI coding assistants called agents.

Supported Agents

Selecting an Agent

The default agent is configured in ~/.conduit/config.toml:

default_agent = "claude"  # or "codex" or "gemini"

Agent Detection

On startup, Conduit searches for:

• claude binary (Claude Code)
• codex binary (Codex CLI)
• gemini binary (Gemini CLI)

Configure custom paths in settings if needed.

Agent Capabilities

All agents can:

• Read and write files
• Execute shell commands
• Search codebases
• Analyze code structure

See individual agent pages for specific features.

Claude Code

Claude Code is Anthropic’s official CLI for Claude.

Features

• Tool Execution — Read, write, and execute commands
• Build/Plan Modes — Toggle between full execution and read-only
• Multiple Models — Opus 4.5, Sonnet 4.5
• 200K Context — Large context window

Models

Build vs Plan Mode

• Build Mode (default) — Full capabilities
• Plan Mode — Read-only analysis, no file modifications

Toggle with Tab or Ctrl+4.

Tools Available

• Read — Read file contents
• Write — Create or overwrite files
• Edit — Modify existing files
• Bash — Execute shell commands
• Glob — Find files by pattern
• Grep — Search file contents

Installation

npm install -g @anthropic-ai/claude-code

Codex CLI

Codex CLI is OpenAI’s command-line coding assistant.

Features

• Full Automation — Executes code autonomously
• 272K Context — Extended context window
• GPT-5.2-Codex — OpenAI’s latest coding model

Models

Automation Mode

Codex runs in full automation mode, executing actions without confirmation prompts.

Tools Available

Similar capabilities to Claude Code:

• File reading and writing
• Shell command execution
• Code search and analysis

Installation

Follow the official installation guide.

Configuration

Ensure Codex is in your PATH, or configure the path:

[tools]
codex = "/path/to/codex"

Gemini CLI

Gemini CLI is Google’s command-line interface for Gemini.

Features

• Large Context Window — 1M token context window
• Tool Execution — Read, write, and execute commands
• Multiple Models — Various Gemini models available

Models

Build vs Plan Mode

Plan mode for Gemini is prompt-guided (best-effort). The agent follows the prompt guidance but isn’t strictly enforced like Claude Code.

Toggle with Tab or Ctrl+4.

Tools Available

Similar capabilities to other agents:

• File reading and writing
• Shell command execution
• Code search and analysis

Installation

npm install -g @google/gemini-cli

Configuration

Ensure Gemini CLI is in your PATH, or configure the path:

[tools]
gemini = "/path/to/gemini"

Build vs Plan Mode

Conduit supports two operational modes across agents.

Build Mode (Default)

In Build mode, the agent has full capabilities:

• Read files
• Write and edit files
• Execute shell commands
• Make changes to your codebase

Plan Mode

In Plan mode, the agent is read-only:

• Can read files
• Can search the codebase
• Can analyze code
• Cannot modify files
• Cannot execute commands

When to Use Each

Use Build Mode when:

• Implementing features
• Fixing bugs
• Refactoring code
• Running tests

Use Plan Mode when:

• Exploring unfamiliar code
• Getting explanations
• Planning before implementation
• Reviewing architecture

Toggling Modes

Visual Indicator

The status bar shows the current mode:

• Build — Full execution enabled
• Plan — Read-only mode

Note

Plan mode is strictly enforced by Claude Code. Codex and Gemini follow the prompt guidance, so treat it as best-effort.

User Interface Overview

Conduit’s TUI is designed for efficient keyboard-driven workflows.

Layout

┌─────────────────────────────────────────────────────────────┐
│  Tab 1  │  Tab 2  │  Tab 3                                  │ Tab Bar
├─────────┬───────────────────────────────────────────────────┤
│         │                                                   │
│ Projects│               Chat Area                           │
│         │                                                   │
│ > repo1 │  Messages, tool outputs, and responses            │
│   main  │                                                   │
│   feat  │                                                   │
│         │                                                   │
│ > repo2 │                                                   │
│   main  │                                                   │
│         │                                                   │
├─────────┴───────────────────────────────────────────────────┤
│                     Input Box                               │
├─────────────────────────────────────────────────────────────┤
│ Tokens: 1.2K/500  │  $0.02  │  main  │  Build  │  Claude   │ Status
└─────────────────────────────────────────────────────────────┘

Components

• Tab Bar — Open sessions
• Sidebar — Project tree
• Chat View — Conversation
• Status Bar — Info display
• Command Palette — Quick actions

Keyboard-First Design

All interactions are keyboard-driven. Use ? or :help to see available shortcuts.

Sidebar

Documentation coming soon.

See Quick Reference for keyboard shortcuts.

Chat View

Documentation coming soon.

See Quick Reference for keyboard shortcuts.

Tab Bar

Documentation coming soon.

See Quick Reference for keyboard shortcuts.

Status Bar

Documentation coming soon.

See Quick Reference for keyboard shortcuts.

Command Palette

Documentation coming soon.

See Quick Reference for keyboard shortcuts.

Keyboard Shortcuts Quick Reference

All keyboard shortcuts in one place. Use conduit debug-keys to verify how your terminal reports key combinations.

Global Shortcuts

These work in all modes unless overridden by context-specific bindings.

Readline-Style Editing

Scrolling (Global)

Chat Mode

Scrolling Mode

Entered when scrolling through chat history.

Sidebar Mode

Dialog Mode

Project Picker

Model Selector

Command Palette

Theme Picker

Session Import

Raw Events View

Key Notation

When customizing keybindings in config.toml:

Terminal Compatibility

Some key combinations may not work in all terminals:

• Ctrl+\ is often reported as Ctrl+4 — use conduit debug-keys to check
• Ctrl+Shift combinations may not be recognized by all terminals
• Alt key behavior varies (some terminals use Escape prefix)

Run conduit debug-keys to see exactly what key events your terminal sends.

Global Shortcuts

See Quick Reference for the complete shortcut list.

Chat Shortcuts

See Quick Reference for the complete shortcut list.

Scrolling Shortcuts

See Quick Reference for the complete shortcut list.

Sidebar Shortcuts

See Quick Reference for the complete shortcut list.

Dialogs Shortcuts

See Quick Reference for the complete shortcut list.

Configuration Overview

Conduit is configured via ~/.conduit/config.toml.

Config File Location

~/.conduit/config.toml

The file is created automatically on first run with default values.

Configuration Sections

• Config File — Full file reference
• Keybindings — Customize shortcuts
• Tool Paths — Agent binary locations
• Themes — Visual customization

Example Configuration

# Default agent
default_agent = "claude"

# Token display
show_token_usage = true
show_cost = true

# Theme
[theme]
name = "catppuccin-mocha"

# Custom tool paths
[tools]
claude = "/opt/homebrew/bin/claude"

Reloading Config

Changes take effect on restart. Some settings (like theme) can be changed at runtime.

Config File Reference

Complete reference for ~/.conduit/config.toml.

Application Settings

# Default agent: "claude", "codex", or "gemini"
default_agent = "claude"

# Working directory for agents (defaults to current directory)
# working_dir = "/path/to/default"

# Maximum concurrent tabs
max_tabs = 10

# Token usage display
show_token_usage = true
show_cost = true

# Cost calculation (per million tokens)
claude_input_cost_per_million = 3.0
claude_output_cost_per_million = 15.0

Theme Configuration

[theme]
# Built-in theme name
name = "default-dark"

# Or custom theme path
# path = "~/.conduit/themes/my-theme.toml"

Built-in themes: default-dark, default-light, catppuccin-mocha, catppuccin-latte, tokyo-night, dracula

Tool Paths

[tools]
git = "/usr/bin/git"
gh = "/usr/local/bin/gh"
claude = "/opt/homebrew/bin/claude"
codex = "/usr/local/bin/codex"
gemini = "/usr/local/bin/gemini"

Selection & Clipboard

[selection]
# Copy immediately when mouse selection ends
auto_copy_selection = true
# Clear the selection after copying
clear_selection_after_copy = true

Keybindings

See Keybindings for customization.

Keybindings Configuration

Customize keyboard shortcuts in ~/.conduit/config.toml.

Key Notation

Contexts

Keybindings are organized by context:

• [keys] — Global (all modes)
• [keys.chat] — Chat input
• [keys.scrolling] — Scrolling mode
• [keys.sidebar] — Sidebar navigation
• [keys.dialog] — Dialog interactions
• [keys.project_picker] — Project picker
• [keys.model_selector] — Model selection

Example Customization

# Global keybindings
[keys]
"C-s" = "Submit"           # Ctrl+S to submit
"M-q" = "Quit"             # Alt+Q to quit

# Chat-specific
[keys.chat]
"C-Enter" = "Submit"       # Ctrl+Enter to submit

# Sidebar
[keys.sidebar]
"a" = "AddRepository"      # Press 'a' to add repo

Available Actions

See Shortcuts Reference for all available actions.

Debugging

Use conduit debug-keys to see how your terminal reports key combinations.

Tool Paths

Configure paths to external tools.

Default Detection

Conduit searches your PATH for:

• git — Required
• gh — GitHub CLI (optional)
• claude — Claude Code agent
• codex — Codex CLI agent
• gemini — Gemini CLI agent

Custom Paths

If tools aren’t in your PATH, specify them:

[tools]
git = "/usr/bin/git"
gh = "/usr/local/bin/gh"
claude = "/opt/homebrew/bin/claude"
codex = "/home/user/.local/bin/codex"
gemini = "/home/user/.local/bin/gemini"

Verifying Paths

Check tool detection:

# Should show tool locations
which claude codex gemini git gh

Missing Tools

If a required tool is missing, Conduit shows a dialog on startup with options to:

• Configure the path manually
• Skip (if optional)

Themes

Customize Conduit’s appearance with themes.

Built-in Themes

Selecting a Theme

Via Config File

[theme]
name = "catppuccin-mocha"

At Runtime

Press Alt+T to open the theme picker.

Theme Discovery

Conduit auto-discovers:

• Built-in themes
• VS Code themes from ~/.vscode/extensions/
• Custom themes in ~/.conduit/themes/

More Information

• Built-in Themes — Screenshots and details
• Custom Themes — Create your own
• VS Code Migration — Convert VS Code themes

Builtin Themes

Documentation coming soon.

See Themes Overview for general information.

Custom Themes

Documentation coming soon.

See Themes Overview for general information.

Vscode Migration Themes

Documentation coming soon.

See Themes Overview for general information.

conduit

The main Conduit TUI application.

Usage

conduit [OPTIONS]

Options

Examples

# Start Conduit with default settings
conduit

# Use a custom data directory
conduit --data-dir ~/my-conduit-data

Environment

Conduit uses the following environment variables:

• HOME — For default data directory location
• PATH — For finding agent binaries

Data Directory

The data directory contains:

• config.toml — Configuration
• conduit.db — Session database
• logs/ — Application logs
• workspaces/ — Workspace data
• themes/ — Custom themes

conduit debug-keys

Debug keyboard input to troubleshoot keybinding issues.

Usage

conduit debug-keys

Purpose

Different terminals report key combinations differently. Use this command to:

• See exactly what key events your terminal sends
• Troubleshoot keybindings that don’t work
• Find the correct notation for custom keybindings

Output

The command shows:

• Key code
• Modifier keys pressed
• The Conduit key notation

Example

Press keys to see their codes. Press Ctrl+C to exit.

Key: Char('4'), Modifiers: CONTROL
  → Notation: C-4

Key: Tab, Modifiers: ALT
  → Notation: M-Tab

Common Issues

Use the reported notation in your config.toml keybindings.

conduit migrate-theme

Convert VS Code themes to Conduit’s native TOML format.

Usage

conduit migrate-theme INPUT [OPTIONS]

Arguments

Options

Examples

# Convert a VS Code theme
conduit migrate-theme ~/.vscode/extensions/theme-dracula/theme.json

# Specify output location
conduit migrate-theme theme.json --output ~/my-theme.toml

# Extract color palette
conduit migrate-theme theme.json --palette

Output Format

The generated TOML file can be used directly:

[theme]
path = "~/.conduit/themes/my-theme.toml"

Supported Themes

Most VS Code color themes are supported. The migration extracts:

• Editor colors
• Syntax highlighting
• UI element colors

Worktrees

Documentation coming soon.

Branch Status

Documentation coming soon.

Pr Tracking

Documentation coming soon.

Token Usage & Cost Tracking

Monitor your AI usage in real-time.

Status Bar Display

The status bar shows:

• Input tokens — Tokens sent to the model
• Output tokens — Tokens received
• Estimated cost — Based on model pricing

Configuration

# Enable/disable display
show_token_usage = true
show_cost = true

# Pricing (per million tokens)
claude_input_cost_per_million = 3.0
claude_output_cost_per_million = 15.0

Toggle Display

Press Alt+P to toggle the metrics display.

Model Pricing

Context Window

The display also shows context usage relative to the model’s limit (e.g., 200K for Claude).

Session Import

Documentation coming soon.

Data Storage

Documentation coming soon.

Troubleshooting

Documentation coming soon.

Shortcuts Reference

Documentation coming soon.

See the related documentation sections for current information.

Config Reference

Documentation coming soon.

See the related documentation sections for current information.

Theme Properties Reference

Documentation coming soon.

See the related documentation sections for current information.