AgentScope

Workflow analysis and visualization tool for AI coding agents. Parses local logs from Claude Code and Codex, extracts complete work records, computes token consumption and phase distribution, and provides a visual interface for understanding agent behavior.

Features

• Dual agent support — Parse and analyze sessions from both Claude Code and OpenAI Codex
• Phase annotation — Rule-based classification of agent activity into phases (exploration, generation, debugging, testing, communication)
• Five-dimension evaluation — Radar-chart comparison across Effectiveness, Cost Efficiency, Exploration Efficiency, Iteration Efficiency, and Autonomy
• Web UI with four views — Session Timeline, Session Dashboard, Project Overview, Agent Comparison
• Real-time monitoring — Watch active sessions with live token burn rate and phase breakdown
• Git Sync — Export sessions to .agentscope/ directories for team sharing via Git
• Cost tracking — Per-model cost estimation with configurable pricing

Quick Start

# Install from source
git clone https://github.com/anthropics/agentscope.git
cd agentscope
npm install && cd web && npm install && cd ..
npm run build
npm link

# Parse recent sessions
agentscope parse

# View aggregate statistics
agentscope stats

# Launch the web UI
agentscope view

The web UI opens at http://localhost:3333 by default.

CLI Commands

agentscope parse

Parse agent session logs and populate the local cache.

Options:
  -s, --session <id>      Parse a specific session by ID (prefix match)
  -p, --project <filter>  Filter by project path substring
  -n, --limit <n>         Limit number of sessions to parse (default: 20)
  -a, --all               Parse all sessions (no limit)
  --json                  Output raw JSON instead of formatted text
  --no-cache              Skip writing to cache

agentscope stats

Show statistics from cached sessions.

Options:
  -s, --session <id>      Show detailed stats for a specific session
  -p, --project <filter>  Filter by project path substring
  -n, --limit <n>         Number of sessions to show (default: 10)
  --json                  Output raw JSON

agentscope watch

Watch an active session in real-time with auto-refreshing terminal UI.

Options:
  -s, --session <id>      Watch a specific session
  -p, --project <filter>  Filter by project path substring
  -i, --interval <ms>     Poll interval in milliseconds (default: 3000)

agentscope view

Start the AgentScope web UI.

Options:
  -p, --port <port>       Port to listen on (default: 3333)
  -s, --session <id>      Open directly to a specific session
  --no-open               Don't open the browser automatically

agentscope sync

Export sessions to project .agentscope/ directories for Git sharing.

Options:
  -s, --session <id>      Sync a specific session (prefix match)
  -p, --project <filter>  Filter by project path substring
  -a, --all               Sync sessions from all projects (default: current project only)
  --dry-run               Preview without writing files
  --force                 Overwrite existing exported files

agentscope import [path]

Import sessions from .agentscope/ directory into local cache for Web UI viewing.

Arguments:
  path                    Path to sessions directory (default: .agentscope/sessions/)

Options:
  --force                 Re-import sessions that already exist in cache

agentscope unsync

Remove .agentscope/ directory from projects.

Options:
  -s, --session <id>      Remove a specific session (prefix match on sessionId)
  -a, --all               Remove .agentscope/ from all projects that have one
  --dry-run               Preview without deleting

Web UI

Launch with agentscope view. Four views are available:

Session Timeline — Vertical conversation flow showing phase distribution bar, per-turn statistics, user/assistant messages, expandable tool calls, and nested sub-agent groups.

Session Dashboard — Metric cards (tokens, cost, duration, efficiency), phase distribution pie chart, model usage bar chart, and file change list.

Project Overview — Aggregated project statistics, token usage trend chart, and session list with pagination.

Agent Comparison — Side-by-side agent type comparison with five-dimension radar chart, metrics comparison table with delta highlighting, and phase distribution breakdown.

Architecture

Four-layer architecture:

Raw Logs ──▶ Parser ──▶ Analyzer ──▶ Storage ──▶ Viewer
              │            │            │           │
          JSONL parse   Phase tag    Cache +     Web UI
          Message rebuild  Cost calc   Git sync   REST API
          Tool extraction  Efficiency

1. Parser — Reads Claude Code / Codex JSONL logs, rebuilds conversation trees, extracts tool calls and token usage into a unified AgentSession structure
2. Analyzer — Annotates phases (rule-based classification of 50+ bash command patterns), calculates cost estimates, computes efficiency metrics and repair cycle detection
3. Storage — Local cache (~/.agentscope/cache/) for parsed sessions, .agentscope/ project directories for Git-based team sharing
4. Viewer — HTTP server serving REST API + React SPA (Recharts visualizations, dark theme)

Directory Structure

src/
├── parser/
│   ├── index.ts                    # Route: parseSession()
│   ├── session-discovery.ts        # Discover sessions from all agent sources
│   ├── claude-code/                # Claude Code log parser (7 modules)
│   └── codex/                      # Codex log parser (4 modules)
├── analyzer/
│   ├── phase-annotator.ts          # Rule-based phase classification
│   ├── bash-classifier.ts          # Bash command categorization (50+ patterns)
│   ├── cost-calculator.ts          # Per-model cost estimation
│   ├── summary-calculator.ts       # Token aggregation + efficiency metrics
│   └── index.ts
├── cli/                            # 7 CLI commands
├── server/
│   ├── index.ts                    # HTTP server (static files + SPA fallback)
│   └── api.ts                      # REST API endpoints
├── storage/
│   ├── cache.ts                    # ~/.agentscope/cache/ read/write
│   └── sync.ts                     # Git sync export logic
├── types.ts                        # Core type definitions
└── utils/
web/                                # React + Vite frontend
├── src/
│   ├── pages/                      # HomePage, SessionPage, ProjectPage, ComparePage
│   ├── components/                 # layout, timeline, dashboard, overview
│   ├── api/client.ts               # Fetch wrapper
│   └── styles/index.css            # Dark theme CSS

Supported Agents

Claude Code

• Log location: ~/.claude/projects/<project-hash>/<session-id>.jsonl
• Features: Full conversation tree reconstruction, sub-agent parsing, streaming message assembly, sidechain handling, cache token tracking
• Models: Claude Opus, Sonnet, Haiku (with per-model pricing)

Codex (OpenAI)

• Log location: ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl
• Features: Task-based turn segmentation, function_call/custom_tool_call mapping, reasoning token tracking
• Models: GPT-5.3 Codex, GPT-4o (configurable pricing via ~/.agentscope/pricing.json)

Development

# Install dependencies
npm install
cd web && npm install

# Build everything (backend + frontend)
npm run build

# Run tests
npm test

# Development mode (backend, watch)
npm run dev

# Development mode (frontend, Vite HMR with API proxy)
npm run dev:web

# Run CLI from source
node dist/index.js

Requires Node.js >= 18.0.0.

Publishing to npm

First-time setup:

# Login to npm (one-time)
npm login

# Build everything before publishing
npm run build

# Publish (dry run to verify package contents)
npm publish --dry-run

# Publish for real
npm publish

After publishing, users can install and use directly:

npx agentscope parse
npx agentscope view

# Or install globally
npm install -g agentscope
agentscope parse

Updating the npm Package

# Bump version (patch: 0.1.0 → 0.1.1)
npm version patch

# Or minor: 0.1.0 → 0.2.0
npm version minor

# Or major: 0.1.0 → 1.0.0
npm version major

# Build and publish
npm run build
npm publish

npm version automatically creates a git commit and tag. Push both to remote:

git push && git push --tags

Custom Pricing

Override model pricing by creating ~/.agentscope/pricing.json:

{
  "gpt-5.3-codex": {
    "inputPer1M": 2.00,
    "outputPer1M": 8.00,
    "cacheReadPer1M": 0.50,
    "cacheCreationPer1M": 0
  }
}

API Reference

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/sessions | List sessions (supports ?project=, ?limit=, ?offset=) | | GET | /api/sessions/active | Get recently active sessions (last 5 minutes) | | GET | /api/sessions/:id | Get full session with turns (supports ?live=true) | | GET | /api/sessions/:id/summary | Get session meta + summary only | | GET | /api/overview | Global statistics (tokens, cost, phase/model/agent breakdown) | | GET | /api/projects | List all projects with aggregated stats | | GET | /api/projects/:name | Get project detail with session list | | GET | /api/compare | Agent comparison data with five-dimension scores (supports ?project=) |

License

MIT