devctx

README

devctx

日本語

A CLI tool for managing Claude Code sessions and git worktrees with Mind Map visualization.

See all your sessions at a glance — what's active, what's blocked, and where each task is heading.

Drill into a project to see the semantic task flow — branching, merging, and rejected tasks visualized as a DAG.

Features

• Mind Map View - Semantic DAG visualization of task flows (branching, merging, rejection)
• Kanban View - Visualize session states at a glance
• AI Insights - Claude infers goal, focus, next step, and attention state for each session
• Auto Session Tracking - Automatic registration via Claude Code hooks
• Status Management - in-progress / review / blocked / done
• Shell Integration - One-command context switching
• fzf Integration - Interactive context selection
• TUI Dashboard - Interactive UI powered by Bubble Tea
• Time Tracking - Accumulated work time per session
• GitHub Integration - Auto-detect and link Issues/PRs
• Worktree Creation - Create branch to Claude launch in one command
• Session Roadmap - Auto-detect development phases

Installation

go install github.com/hiroyannnn/devctx@latest

Or build from source:

git clone https://github.com/hiroyannnn/devctx.git
cd devctx
go build -o devctx .
mv devctx ~/.local/bin/  # or /usr/local/bin/

Quick Start

# Set up Claude Code hooks (auto session tracking)
devctx hooks --install

# Open the Mind Map dashboard
devctx roadmap serve

That's it. Start using Claude Code as usual — sessions are tracked automatically via hooks.

Optional Setup

# Install slash commands for Claude Code (/devctx-review, /devctx-done, etc.)
devctx commands --install

# Enable shell shortcuts (add to .bashrc / .zshrc)
eval "$(devctx shell-init)"

Kanban View Example

🚀 In Progress
╭──────────────────────────────────────────────╮
│ [auth]                                       │
│   💬 zesty-hopping-falcon                    │
│   ⎇ feature/auth                             │
│   ⏱ 2h ago  ⌛ 4h32m                         │
│   📝 Working on OAuth2 refresh tokens        │
╰──────────────────────────────────────────────╯

👀 Review
╭──────────────────────────────────────────────╮
│ [api-fix]                                    │
│   💬 playful-coding-knuth                    │
│   ⎇ fix/api-error                            │
│   ⏱ 30m ago                                  │
│   🔀 https://github.com/user/repo/pull/123   │
│   ☑ /compact                                 │
│   ☐ /create-pr                               │
╰──────────────────────────────────────────────╯

💬 shows Claude Code's auto-generated session name (slug).

Commands

Basic Operations

Command	Description
devctx list	Display contexts in kanban view
devctx tui	Open interactive TUI dashboard
devctx show <name>	Show context details
devctx register <name>	Register a context (usually auto via hook)
devctx resume <name>	Resume a context
devctx move <name> <status>	Change status
devctx touch <name>	Update context's last-seen timestamp
devctx archive <name>	Archive as done
devctx remove <name>	Remove a context from tracking

Creation & Configuration

Command	Description
devctx new <branch>	Create worktree + cd + claude in one go
devctx note <name> [msg]	Add/show a note
devctx link <name> <url>	Link GitHub Issue/PR
devctx hooks [--install]	Set up Claude Code hooks
devctx commands [--install]	Set up Claude slash commands

GitHub Integration

Command	Description
devctx sync [name]	Auto-detect and link PR/Issue
devctx sync --all	Update session names for all contexts
devctx pr <name>	Create a PR

Session Roadmap

Command	Description
devctx roadmap scan	Show git-based phases for all sessions
devctx roadmap status	Visual progress through development phases
devctx roadmap serve	Start web dashboard (localhost:3333)
devctx roadmap refresh	Full re-scan with PR detection (uses gh CLI)
devctx roadmap analyze [name]	Generate AI insights via Claude CLI
devctx roadmap analyze --all	Generate insights for all active sessions
devctx roadmap init --prompt "..."	Set initial prompt for a session
devctx insight [name]	Show/set session insights manually

Monitoring & Search

Command	Description
devctx discover	Find existing Claude Code sessions
devctx discover --import	Import discovered sessions
devctx status	Show live status of all contexts
devctx status --watch	Continuously monitor status
devctx search <query>	Search through session history

Maintenance

Command	Description
devctx stats	Show statistics
devctx clean	Remove old contexts (default: done > 30 days)
devctx clean --days=7	Remove contexts older than 7 days
devctx clean --done=false	Remove old contexts regardless of status
devctx clean --dry-run	Preview what would be removed

Shell Integration

Add to .bashrc or .zshrc:

eval "$(devctx shell-init)"

Shortcuts:

• dx - Select context via fzf and resume (shows list if fzf not available)
• dx <name> - Resume context (cd + claude --resume)
• dx - - Resume last touched context
• dxl - List contexts
• dxw - Watch mode (interactive kanban)
• dxm <name> <status> - Change status
• dxn <branch> - Create new worktree
• dxs - Sync GitHub info
• dxt - Open TUI dashboard
• dxp - Show live status
• dxf <query> - Search session history
• dxd - Discover existing sessions

Watch Mode

Interactive kanban view with keyboard controls:

devctx list -w   # or dxw

Navigation:

• ↑/↓ or j/k - Move cursor
• g/G - Jump to top/bottom

Actions:

• Enter or c - Copy resume command to clipboard
• o - Open in new terminal

Status Changes:

• r - Move to Review
• p - Move to In Progress
• b - Move to Blocked
• D - Move to Done
• x - Delete context
• q - Quit

Configuration

Config file: ~/.config/devctx/config.yaml

# Show completed items for N days (default: 1)
done_retention_days: 1

# Disable auto-import of sessions (default: true)
auto_import: false

statuses:
  - name: in-progress
    next: [review, blocked, done]
  - name: review
    next: [in-progress, done]
    checklist:
      - /compact
  - name: blocked
    next: [in-progress]
  - name: done
    next: []
    archive: true
    checklist:
      - /create-pr

Customizing Checklists

Add items to confirm during status transitions:

statuses:
  - name: review
    next: [in-progress, done]
    checklist:
      - /compact
      - /code-simplifier
      - "PR draft created?"

Claude Code Custom Commands

Install slash commands for Claude Code:

devctx commands --install

This creates:

• /devctx-review - Move to review status
• /devctx-done - Mark as done
• /devctx-blocked - Mark as blocked
• /devctx-note - Add a note
• /devctx-link - Link Issue/PR
• /devctx-status - Show context status
• /devctx-insight - Save session insights (goal, focus, next step, state)

A rule file (~/.claude/rules/devctx-insight-auto.md) is also installed, which instructs Claude to automatically run /devctx-insight after creating implementation plans.

Session Roadmap

The roadmap tracks your development lifecycle automatically.

Phase Detection

Phases are auto-detected from git state on register / touch:

Phase	Condition
Idle	No changes, no commits ahead
Implementation	Uncommitted changes
Committed	Commits ahead of base branch
Pushed	Remote branch up to date
PR Open	Open pull request detected
Done	Merged pull request

Milestone Tracking

Development milestones are automatically recorded as events:

Milestone	Source
First Commit / Commits	git log on register / touch
First Push	git remote check
PR Created / Merged	gh CLI on roadmap refresh
Session Start / End	Claude Code hooks
Status Changes	devctx move commands

Events are stored in ~/.config/devctx/events.yaml as an append-only log.

AI Insights

Claude can infer session context and save it as insights:

# Install custom commands + auto-execution rule
devctx commands --install

# In Claude Code, after a plan is created:
# Claude automatically runs /devctx-insight

# Or manually trigger analysis via Claude CLI:
devctx roadmap analyze

Insights include:

• Goal - What this session is trying to achieve
• Current Focus - What's being worked on now
• Next Step - What should be done next
• Attention State - active / waiting / idle / blocked
• Topics - Semantic themes extracted from git and LLM (e.g., "auth", "error handling")
• Tasks - Concrete work items with status (planned / in_progress / done / blocked)

Topic/task extraction uses a hybrid approach: mechanical extraction from git (branch names, commit messages, changed directories) combined with LLM-based clustering and normalization.

Web Dashboard

devctx roadmap serve

Opens a web dashboard at http://localhost:3333 with:

• Project grouping - Sessions grouped by repository
• Phase pipeline - Visual progress through development phases
• Milestone chips - Sessions/Commits/Pushed/PR status at a glance
• Topics & Tasks - Semantic topics and task lists per session
• Event timeline - Click a card to expand its full event history
• Project / Flat / Mind Map view - Switch between grouped, flat, and mind map layouts
• Mind Map view - Semantic DAG visualization with task branching, merging, and rejection. Drag nodes to rearrange.

Troubleshooting

Hooks not working

1. Check settings with devctx hooks
2. Run /hooks in Claude Code to approve
3. Ensure devctx is in PATH

Session not auto-registered

• Verify SessionStart hook is properly configured
• Test manually with devctx register

resume doesn't change directory

Due to shell constraints, subprocesses cannot change the parent shell's directory. Use shell integration (eval "$(devctx shell-init)") or manually execute the displayed commands.

License

MIT