ViewScreen

A real-time terminal UI for monitoring Claude Code sub-agent operations. ViewScreen displays active agents, tasks, and session metrics through an LCARS-inspired interface.

Features

• Real-time agent monitoring - See sub-agents as they spawn, run, and complete
• Task tracking - View tasks created during Claude Code sessions
• Activity timeline - Watch tool invocations as they happen
• Session metrics - Track tool usage, active agents, duration, and errors
• LCARS-inspired design - Star Trek aesthetic with amber, blue, magenta, and salmon color scheme

Installation

Requirements

• Python 3.10 or higher
• pip

Install from source

git clone https://github.com/hl/viewscreen.git
cd viewscreen
pip install -e .

Usage

Basic usage

Monitor the current directory's Claude Code session:

viewscreen .

Monitor a specific project:

viewscreen ~/Projects/my-project

Command-line options

viewscreen [project_path] [-s SESSION]

Arguments:
  project_path          Path to the project directory (default: current directory)

Options:
  -s, --session ID      Monitor a specific session by ID (prefix match supported)
  -h, --help            Show help message

Specifying a session

If you have multiple Claude Code sessions in a project, ViewScreen automatically monitors the most recently active one. To monitor a specific session:

# Use the first 8 characters of the session ID
viewscreen . -s c1fbdb2d

You can find the session ID by asking Claude Code: "what is the session id?"

Custom task directory

If you use a custom task list ID (via CLAUDE_CODE_TASK_LIST_ID environment variable), set the same variable when running ViewScreen:

CLAUDE_CODE_TASK_LIST_ID=my-project-tasks viewscreen .

Interface

┌─────────────────────────────────────────────────────────────────┐
│ VIEWSCREEN                              2024-02-03 14:30:45     │
│ Project: my-project  Session: c1fbdb2d  Status: MONITORING      │
├─────────────────────────────────────────────────────────────────┤
│ AGENTS                                                          │
│ ● swift-fox Explorer Agent                                      │
│ ○ clever-bear Plan Agent                                        │
├─────────────────────────────────────────────────────────────────┤
│ TASKS                                                           │
│ ● #1 Implement feature X                                        │
│ ✓ #2 Write tests                                                │
├─────────────────────────────────────────────────────────────────┤
│ ACTIVITY                                                        │
│ 14:30:42  Task    Explore: Search codebase                      │
│ 14:30:38  Bash    npm install                                   │
│ 14:30:35  Read    src/main.ts                                   │
├─────────────────────────────────────────────────────────────────┤
│ METRICS                                                         │
│ Tools: 42          Agents: 2          Duration: 00:15:30        │
│ Model: claude-...  Errors: 0                                    │
└─────────────────────────────────────────────────────────────────┘
│ Q: Quit  ↑↓: Scroll                                             │
└─────────────────────────────────────────────────────────────────┘

Panels

• AGENTS - Active sub-agents with status indicators (● running, ○ pending)
• TASKS - Tasks from the session (● in progress, ○ pending, ✓ completed)
• ACTIVITY - Recent tool invocations with timestamps
• METRICS - Session statistics including tool count, active agents, duration, model, and errors

Keyboard controls

• Q - Quit ViewScreen
• ↑↓ - Scroll within panels
• Tab - Switch focus between panels

How it works

ViewScreen monitors Claude Code sessions by:

1. Discovering session files - Finds JSONL files in ~/.claude/projects/<encoded-path>/
2. Tailing session logs - Watches for new events as Claude Code writes them
3. Tracking agents - Detects Task tool invocations that spawn sub-agents
4. Loading tasks - Reads task files from ~/.claude/tasks/<session-id>/
5. Updating UI - Refreshes the display every second with current state

The path encoding converts project paths like /Users/hl/Projects/my_app to -Users-hl-Projects-my-app (slashes and underscores become dashes).

Troubleshooting

"No Claude Code sessions found"

Make sure you've run Claude Code in the specified directory at least once. ViewScreen looks for session files in ~/.claude/projects/.

Wrong session selected

ViewScreen picks the most recently modified session file. Use --session to specify a different one:

viewscreen . -s <session-id-prefix>

Tasks not appearing

Tasks are stored per-session. Check that:

1. The session ID matches (shown in ViewScreen header)
2. If using CLAUDE_CODE_TASK_LIST_ID, set it for ViewScreen too

Agents not appearing

Agents only appear if started after ViewScreen launches. ViewScreen starts fresh to avoid showing old completed agents.

Development

Project structure

viewscreen/
├── __init__.py
├── __main__.py      # CLI entry point
├── app.py           # Main Textual application
├── discovery.py     # Session file discovery
├── models.py        # Data classes
├── path_encoder.py  # Path encoding utilities
├── tailer.py        # JSONL file tailing
├── tasks.py         # Task loading
├── tracker.py       # Agent state tracking
├── styles.tcss      # LCARS styling
└── widgets/
    ├── __init__.py
    ├── activity_panel.py
    ├── agent_panel.py
    ├── footer.py
    ├── header.py
    ├── metrics_panel.py
    └── task_panel.py

Running from source

# Install in development mode
pip install -e .

# Run
viewscreen .

License

MIT

Credits

Built with Textual - a TUI framework for Python.

Inspired by Star Trek LCARS interface design.