Skip to main content
Launch an interactive terminal UI (TUI) for browsing agent sessions, viewing prompts/thoughts/diffs, and querying with Mubit.

​
Usage

codaph tui [options]
Alias: codaph (default when no command specified)

​
Description

The Codaph TUI provides:
  • Browse View - List sessions by date or individual sessions
  • Inspect View - Deep-dive into session prompts, thoughts, outputs, file changes
  • Chat - Ask questions about sessions using Mubit semantic search
  • Project Manager - Switch between tracked projects
  • Settings - Configure Mubit/OpenAI keys, project ID, actor ID
The TUI reads from your local .codaph/ mirror (no network required except for chat).

​
Flags

​
--cwd
string
Working directory / project path (defaults to current directory)

​
Keyboard Shortcuts

​
Global

  • q or Ctrl+C - Quit
  • ? - Toggle help
  • s - Toggle settings
  • p - Toggle project manager
  • Tab - Switch between Browse/Inspect views

​
Browse View

  • ↑/↓ or j/k - Navigate sessions
  • Enter - Open selected session in Inspect view
  • g - Toggle grouping (session / day)
  • a - Cycle actor filter (all / specific actors)
  • r - Refresh (re-sync from Mubit)

​
Inspect View

  • ←/→ or h/l - Switch panes (Prompts / Thoughts / Files / Diff / Chat)
  • ↑/↓ or j/k - Scroll within pane
  • Enter - Select prompt (in Prompts pane) or view full diff (in Diff pane)
  • Backspace - Return to Browse view
  • / - Open chat
  • Esc - Close chat / overlays

​
Chat

  • Type question and press Enter - Query Mubit for selected session
  • ↑/↓ - Scroll chat history
  • Esc - Close chat

​
Settings

  • ↑/↓ - Navigate settings
  • Enter - Edit selected setting
  • Type value and press Enter - Save
  • Esc - Cancel edit / close settings
Editable settings:
  • Mubit API Key
  • Mubit Project ID
  • Mubit Actor ID
  • OpenAI API Key
  • Project Name

​
Project Manager

  • ↑/↓ - Navigate projects
  • Enter - Switch to selected project
  • d - Remove project from registry
  • a - Add new project (opens directory picker)
  • Esc - Close project manager

​
View Modes

​
Browse View

List agent sessions with metadata: 
┌─ Sessions (45) ───────────────────────────────────────────┐
│ > 2024-01-15  12 sessions  Codex, Claude  1523 events    │
│   2024-01-14   8 sessions  Codex           892 events    │
│   session-abc123  Codex  45 events  12 prompts  5 files  │
└───────────────────────────────────────────────────────────┘
Grouping modes:
  • Day (default) - Group sessions by date
  • Session - Flat list of individual sessions
Toggle with g. Actor filter:
  • all (default) - Show all contributors
  • alice - Show only alice’s prompts
  • bob - Show only bob’s prompts
Cycle with a.

​
Inspect View

Deep-dive into selected session:

​
Prompts Pane

List prompts in chronological order: 
┌─ Prompts (12) ────────────────────────────────────────────┐
│ > [alice] Add user authentication to login page          │
│   [alice] Fix TypeScript errors in auth module           │
│   [bob] Implement password reset flow                    │
└───────────────────────────────────────────────────────────┘
Press Enter to expand selected prompt (shows thoughts, outputs, files).

​
Thoughts Pane

View agent reasoning for selected prompt: 
┌─ Thoughts ────────────────────────────────────────────────┐
│ I'll need to modify the authentication middleware to...  │
│ First, let's check the current auth implementation...    │
│ Looking at the session token validation logic...         │
└───────────────────────────────────────────────────────────┘
Scroll with ↑/↓.

​
Files Pane

List file changes from selected prompt: 
┌─ Files (5) ───────────────────────────────────────────────┐
│ src/auth/middleware.ts         +45  -12                   │
│ src/auth/session.ts            +23   -5                   │
│ tests/auth.test.ts             +67   -0                   │
└───────────────────────────────────────────────────────────┘
+ = lines added, - = lines removed

​
Diff Pane

View unified diff for selected prompt: 
┌─ Diff ────────────────────────────────────────────────────┐
│ --- src/auth/middleware.ts                                │
│ +++ src/auth/middleware.ts                                │
│ @@ -12,6 +12,8 @@                                          │
│ +import { validateToken } from './session'                │
│ +                                                          │
│  export function authMiddleware(req, res, next) {        │
└───────────────────────────────────────────────────────────┘
Press Enter to view full diff in overlay.

​
Chat Pane

Ask questions about the session using Mubit: 
┌─ Chat ────────────────────────────────────────────────────┐
│ You: What changes were made to authentication?           │
│ Mubit: The session implemented token validation...       │
│                                                           │
│ > [Type question and press Enter]                        │
└───────────────────────────────────────────────────────────┘
Requires MUBIT_API_KEY. Optional OPENAI_API_KEY for AI-enhanced responses.

​
Startup Behavior

​
Auto-sync on Startup

If autoWarmTuiOnOpen is enabled (default), TUI runs codaph pull in background: 
┌─ Status ──────────────────────────────────────────────────┐
│ ⠋ RUNNING [##########----] Remote sync 150/1200 · 12s    │
└───────────────────────────────────────────────────────────┘
Disable in settings: 
{
  "syncAutomation": {
    "autoWarmTuiOnOpen": false
  }
}

​
Project Detection

TUI starts in:
  1. Project specified by --cwd
  2. Current directory
  3. Last-used project from registry

​
Examples

​
Launch TUI

codaph tui
# OR
codaph  # default command

​
Launch in Specific Project

codaph tui --cwd ~/my-project

​
Launch from Anywhere

# From any directory, if project is tracked
codaph
# Press 'p' → select project from registry

​
Chat Examples

​
Identity Queries

You: whoami
Mubit: Selected prompt actor: alice
       Actor filter: all
       Contributors: alice (12p), bob (5p)

​
Session Queries

You: What files were changed?
Mubit: - src/auth/middleware.ts: +45, -12
       - src/auth/session.ts: +23, -5
       - tests/auth.test.ts: +67, -0

​
Semantic Queries

You: Explain the authentication changes
Mubit: [Evidence from session]
       - Added token validation middleware
       - Implemented session expiry logic
       - Added unit tests for auth flow
Requires MUBIT_API_KEY for semantic search.

​
Performance

​
Session Cache

TUI caches session analysis to improve browsing speed:
  • .codaph/.tui-cache.json (session metadata)
  • Invalidated when .codaph/ mirror updates

​
Background Sync

Pull operations run in background without blocking UI:
  • Status bar shows progress
  • Sessions refresh when complete

​
Troubleshooting

​
No Sessions Found

Sessions (0)
(No sessions found for this repo)
Fix: 
codaph pull   # Sync cloud activity
codaph push   # Import local agent history

​
Chat Not Working

Error: Mubit is disabled
Fix: 
codaph setup --mubit-api-key mb_live_...
# OR press 's' in TUI → edit Mubit API Key

​
TUI Crashes on Startup

# Check for terminal compatibility issues
echo $TERM
# Should be: xterm-256color, screen-256color, or similar

​
Terminal Requirements

  • Color support: 256-color terminal recommended
  • Unicode: UTF-8 encoding for icons/symbols
  • Minimum size: 80x24 characters (120x40 recommended)

Build docs developers (and LLMs) love

Get started for freeTalk to us