diff --git a/docs/guides/docusaurus-site-guide.md b/docs/guides/docusaurus-site-guide.md index 2dbd55d8..8e0fbf8e 100644 --- a/docs/guides/docusaurus-site-guide.md +++ b/docs/guides/docusaurus-site-guide.md @@ -17,7 +17,9 @@ The dev server hot-reloads on file changes. ``` website/ ├── docs/ # Markdown documentation pages -│ └── intro.md # Main docs entry point +│ ├── intro.md # Getting Started (sidebar_position: 1) +│ ├── td.md # TD task manager docs (sidebar_position: 2) +│ └── git-plugin.md # Git plugin docs (sidebar_position: 3) ├── blog/ # Blog posts (date-prefixed markdown) │ ├── authors.yml # Blog author definitions │ └── tags.yml # Blog tag definitions @@ -65,8 +67,48 @@ export default function Home() { ## Writing Documentation +> **For AI agents**: Use the `dev-docs` skill (`~/.claude/skills/dev-docs/SKILL.md`) when writing documentation. It provides patterns for user-first, scannable docs with proper code examples. + Docs live in `website/docs/` as Markdown files with YAML frontmatter. +### Documentation Principles + +Follow these patterns from the dev-docs skill: + +- **User-first**: Answer "what can I do?" before "how does it work?" +- **Scannable**: Use headers, code blocks, tables for keyboard shortcuts +- **Progressive disclosure**: Quick overview → detailed usage → full reference +- **Working examples**: Every feature needs runnable code, not `...` placeholders + +### Plugin Documentation Pattern + +For Sidecar plugins, use this structure: + +```markdown +# Plugin Name + +One-line description of what it does. + +![Screenshot](/img/screenshots/plugin-name.png) + +## Overview +Brief explanation of the UI layout and core purpose. + +## Feature Section +Description with keyboard shortcut table: + +| Key | Action | +|-----|--------| +| `s` | Stage file | +| `d` | View diff | + +## Navigation +How to move around within the plugin. + +## Command Reference +Complete list of all shortcuts by context. +``` + ### Creating a New Doc ```markdown diff --git a/website/docs/conversations-plugin.md b/website/docs/conversations-plugin.md new file mode 100644 index 00000000..ea38ed9c --- /dev/null +++ b/website/docs/conversations-plugin.md @@ -0,0 +1,190 @@ +--- +sidebar_position: 5 +title: Conversations Plugin +--- + +# Conversations Plugin + +Browse and search your Claude Code sessions with turn-based organization, message expansion, and session analytics—see what your agent has been doing. + +## Overview + +The Conversations plugin provides a two-pane layout: + +- **Left pane**: Session list with search and filters +- **Right pane**: Message detail with expandable turns +- **Draggable divider**: Resize panes to your preference + +Toggle the sidebar with `\` to maximize message space. + +## Session List + +Browse all Claude Code sessions from your local history. + +| Key | Action | +|-----|--------| +| `j`, `↓` | Move down | +| `k`, `↑` | Move up | +| `g` | Jump to first session | +| `G` | Jump to last session | +| `ctrl+d` | Page down | +| `ctrl+u` | Page up | +| `enter` | View selected session | + +### Search & Filter + +| Key | Action | +|-----|--------| +| `/` | Search sessions by title or ID | +| `f` | Filter by project | +| `esc` | Clear search/filter | + +Search matches session titles and conversation content. + +### Session Actions + +| Key | Action | +|-----|--------| +| `y` | Copy session as markdown | +| `o` | Open session in CLI (`claude resume`) | + +## Message View + +Two view modes for reading conversations: + +| Key | Action | +|-----|--------| +| `l` or `r` | Toggle between flow and turn view | + +### Conversation Flow + +Messages display in order, similar to the Claude Code web UI: +- User messages with prompts +- Assistant responses with tool results collapsed +- Expandable tool invocations + +### Turn View + +Groups messages into conversation "turns" (user prompt + assistant response): +- Collapsed by default +- Shows token counts and tool summary +- Expand to see full message content + +## Message Navigation + +| Key | Action | +|-----|--------| +| `j`, `↓` | Next turn/message | +| `k`, `↑` | Previous turn/message | +| `enter` or `d` | Expand/collapse turn or view detail | +| `y` | Copy turn content | +| `o` | Open in CLI | + +### Detail View + +Press `enter` on a turn to see full details in the right pane: + +| Key | Action | +|-----|--------| +| `j`, `↓` | Scroll down | +| `k`, `↑` | Scroll up | +| `ctrl+d` | Page down | +| `ctrl+u` | Page up | +| `y` | Copy detail content | +| `h`, `←` | Return to turn list | +| `esc` | Close detail view | + +## Pane Navigation + +| Key | Action | +|-----|--------| +| `tab` | Switch to next pane | +| `shift+tab` | Switch to previous pane | +| `l`, `→` | Focus message pane | +| `h`, `←` | Focus sidebar | +| `\` | Toggle sidebar visibility | + +## Session Analytics + +View statistics about a session: +- Model usage breakdown (tokens by model) +- File impacts (which files were created/modified) +- Tool invocations (count by tool type) +- Total token consumption + +## Pagination + +Sessions load 50 messages at a time. Scroll to load older messages automatically with "load older" support for long conversations. + +## Incremental Updates + +The plugin watches for new messages and coalesces updates for performance. Your session list stays current as agents work. + +## Render Caching + +Markdown rendering is cached per-message to maintain smooth scrolling even with large conversations. + +## Mouse Support + +- **Click session**: Select and view +- **Click turn**: Expand/collapse +- **Click tool**: Toggle tool result visibility +- **Drag divider**: Resize panes +- **Scroll**: Navigate lists and content + +## State Persistence + +These preferences save across sessions: +- Sidebar width +- View mode (flow/turn) +- Expanded states + +## Command Reference + +All keyboard shortcuts by context: + +### Sidebar Context (`conversations-sidebar`) + +| Key | Action | +|-----|--------| +| `j`, `↓` | Move down | +| `k`, `↑` | Move up | +| `g` | Jump to top | +| `G` | Jump to bottom | +| `ctrl+d` | Page down | +| `ctrl+u` | Page up | +| `/` | Search sessions | +| `f` | Filter by project | +| `enter` | View session | +| `y` | Copy markdown | +| `o` | Open in CLI | +| `l`, `→` | Focus messages | +| `tab` | Focus messages | +| `\` | Toggle sidebar | + +### Messages Context (`conversations-messages`) + +| Key | Action | +|-----|--------| +| `j`, `↓` | Next turn | +| `k`, `↑` | Previous turn | +| `l` or `r` | Toggle view mode | +| `enter`, `d` | Expand/view detail | +| `y` | Copy content | +| `o` | Open in CLI | +| `h`, `←` | Focus sidebar | +| `tab` | Focus sidebar | +| `esc` | Return to sidebar | +| `\` | Toggle sidebar | + +### Detail Context (`conversations-detail`) + +| Key | Action | +|-----|--------| +| `j`, `↓` | Scroll down | +| `k`, `↑` | Scroll up | +| `ctrl+d` | Page down | +| `ctrl+u` | Page up | +| `y` | Copy content | +| `h`, `←` | Close detail | +| `esc` | Close detail | diff --git a/website/docs/files-plugin.md b/website/docs/files-plugin.md new file mode 100644 index 00000000..abd6157a --- /dev/null +++ b/website/docs/files-plugin.md @@ -0,0 +1,226 @@ +--- +sidebar_position: 4 +title: Files Plugin +--- + +# Files Plugin + +Browse, preview, and manage your project files with syntax highlighting, markdown rendering, and fuzzy search—all in a two-pane terminal interface. + +## Overview + +The Files plugin provides a two-pane layout: + +- **Left pane**: Collapsible file tree with directory expansion +- **Right pane**: File preview with syntax highlighting +- **Draggable divider**: Resize panes to your preference + +Toggle the tree pane with `\` to maximize preview space. + +## File Tree + +Navigate your project structure with vim-style keys. + +| Key | Action | +|-----|--------| +| `j`, `↓` | Move down | +| `k`, `↑` | Move up | +| `l`, `→` | Expand directory or open file | +| `h`, `←` | Collapse directory | +| `enter` | Toggle directory expansion | +| `g` | Jump to top | +| `G` | Jump to bottom | + +### Quick Navigation + +| Key | Action | +|-----|--------| +| `ctrl+p` | Quick open (fuzzy file search) | +| `ctrl+s` | Project-wide content search | +| `/` | Filter tree by filename | + +Quick open caches up to 50,000 files and shows 50 results max. Project search finds matches across your entire codebase. + +## File Preview + +View files with syntax highlighting for code and rendered markdown. + +| Key | Action | +|-----|--------| +| `j`, `↓` | Scroll down | +| `k`, `↑` | Scroll up | +| `ctrl+d` | Page down | +| `ctrl+u` | Page up | +| `g` | Jump to top | +| `G` | Jump to bottom | + +### Content Search + +Search within the current file: + +| Key | Action | +|-----|--------| +| `?` | Open content search | +| `n` | Next match | +| `N` | Previous match | +| `esc` | Close search | + +### Preview Features + +- **Syntax highlighting**: Language detection from file extension +- **Markdown toggle**: Press `m` to switch between raw and rendered markdown +- **Image preview**: Terminal graphics protocol support (where available) +- **Large file handling**: Truncated preview with size warning for big files +- **Binary detection**: Shows file size instead of corrupted content + +### Clipboard + +| Key | Action | +|-----|--------| +| `y` | Copy file contents | +| `c` | Copy file path | + +## File Operations + +Create, rename, move, and delete files without leaving the terminal. + +| Key | Action | +|-----|--------| +| `n` | Create new file | +| `N` | Create new directory | +| `r` | Rename file or directory | +| `m` | Move file or directory | +| `d` | Delete (with confirmation) | + +### Copy & Paste + +| Key | Action | +|-----|--------| +| `y` | Yank (mark for copy) | +| `p` | Paste yanked file | + +Yank a file, navigate to the destination, and paste. Works across directories. + +### File Info + +Press `i` to see a modal with: +- Git status (tracked, modified, staged) +- File size +- Last modified date +- File permissions + +## Navigation + +### Pane Switching + +| Key | Action | +|-----|--------| +| `tab` | Switch to next pane | +| `shift+tab` | Switch to previous pane | +| `\` | Toggle tree visibility | + +### Tree to Preview + +| Key | Action | +|-----|--------| +| `l`, `→` | Focus preview pane | +| `enter` | Load file into preview | + +### Preview to Tree + +| Key | Action | +|-----|--------| +| `h`, `←` | Focus tree pane | +| `esc` | Return to tree | +| `\` | Toggle tree (shows if hidden) | + +## Mouse Support + +- **Click file**: Select and preview +- **Click folder**: Expand/collapse +- **Drag divider**: Resize panes +- **Scroll**: Navigate tree or preview +- **Drag in preview**: Select text (multi-line supported) + +## File Watching + +The preview auto-reloads when the file changes on disk. Useful for watching agent modifications in real-time. + +## State Persistence + +These preferences save across sessions: +- Expanded directories +- Cursor position +- Scroll offsets +- Active pane +- Sidebar width + +## Command Reference + +All keyboard shortcuts by context: + +### Tree Context (`file-browser-tree`) + +| Key | Action | +|-----|--------| +| `j`, `↓` | Move down | +| `k`, `↑` | Move up | +| `l`, `→` | Expand / open | +| `h`, `←` | Collapse | +| `enter` | Toggle expand | +| `g` | Jump to top | +| `G` | Jump to bottom | +| `ctrl+p` | Quick open | +| `ctrl+s` | Project search | +| `/` | Filter files | +| `n` | Create file | +| `N` | Create directory | +| `r` | Rename | +| `m` | Move | +| `d` | Delete | +| `y` | Yank | +| `p` | Paste | +| `c` | Copy path | +| `i` | File info | +| `tab` | Focus preview | +| `\` | Toggle tree | + +### Preview Context (`file-browser-preview`) + +| Key | Action | +|-----|--------| +| `j`, `↓` | Scroll down | +| `k`, `↑` | Scroll up | +| `ctrl+d` | Page down | +| `ctrl+u` | Page up | +| `g` | Jump to top | +| `G` | Jump to bottom | +| `?` | Content search | +| `n` | Next match | +| `N` | Previous match | +| `m` | Toggle markdown | +| `y` | Copy contents | +| `c` | Copy path | +| `h`, `←` | Focus tree | +| `esc` | Return to tree | +| `\` | Toggle tree | + +### Quick Open (`file-browser-quickopen`) + +| Key | Action | +|-----|--------| +| type | Filter files | +| `j`, `↓` | Next result | +| `k`, `↑` | Previous result | +| `enter` | Open file | +| `esc` | Cancel | + +### Project Search (`file-browser-project-search`) + +| Key | Action | +|-----|--------| +| type | Search query | +| `j`, `↓` | Next result | +| `k`, `↑` | Previous result | +| `enter` | Open file at match | +| `esc` | Cancel | diff --git a/website/docs/git-plugin.md b/website/docs/git-plugin.md new file mode 100644 index 00000000..51684444 --- /dev/null +++ b/website/docs/git-plugin.md @@ -0,0 +1,324 @@ +--- +sidebar_position: 3 +title: Git Plugin +--- + +# Git Plugin + +A full-featured git interface for staging, diffing, committing, and managing branches—all without leaving your terminal. Watch your agent's changes in real-time with side-by-side diffs and inline previews. + +![Git Status](/img/screenshots/sidecar-git.png) + +## Overview + +The Git plugin provides a three-pane layout: + +- **Left pane**: File tree (staged, modified, untracked) + recent commits +- **Right pane**: Diff preview or commit details +- **Draggable divider**: Resize panes to your preference + +Changes auto-refresh as your agent works, so you always see the current state. + +## File Status + +Files are organized into sections with status indicators: + +| Symbol | Status | Meaning | +|--------|--------|---------| +| `M` | Modified | File changed | +| `A` | Added | New file (staged) | +| `D` | Deleted | File removed | +| `R` | Renamed | File renamed | +| `?` | Untracked | New file not tracked | +| `U` | Unmerged | Merge conflict | + +Each file shows `+/-` line counts for quick impact assessment. + +## Staging & Unstaging + +| Key | Action | +|-----|--------| +| `s` | Stage selected file or folder | +| `u` | Unstage selected file | +| `S` | Stage all files | +| `D` | Discard changes (with confirmation) | + +Stage entire folders by selecting the folder and pressing `s`. After staging, the cursor automatically moves to the next unstaged file. + +## Diff Viewing + +View changes inline or in full-screen mode with syntax highlighting. + +| Key | Action | +|-----|--------| +| `d` | Open full-screen diff | +| `v` | Toggle unified / side-by-side view | +| `h/l` | Scroll horizontally (wide diffs) | +| `0` | Reset horizontal scroll | +| `esc`, `q` | Close diff | + +![Side-by-side Diff](/img/screenshots/sidecar-git-diff-side-by-side.png) + +### Diff Modes + +- **Unified**: Traditional line-by-line format with `+` and `-` markers +- **Side-by-side**: Split view showing before/after columns + +Your preferred mode persists across sessions. + +### Diff Sources + +- **Modified files**: Working directory changes (`git diff`) +- **Staged files**: Changes ready to commit (`git diff --cached`) +- **Untracked files**: Shows all lines as additions +- **Commits**: View what changed in any commit + +## Commit Workflow + +1. Stage files with `s` or `S` +2. Press `c` to open the commit modal +3. Enter your commit message (multi-line supported) +4. Press `ctrl+s` or Tab to button and Enter + +The modal shows: +- Count of staged files +- Total lines added/removed +- List of files being committed +- Message textarea + +If commit fails (hooks, etc.), your message is preserved for retry. + +## Branch Management + +| Key | Action | +|-----|--------| +| `b` | Open branch picker | + +The branch picker shows: +- All local branches +- Current branch highlighted +- Upstream tracking info (`↑N ↓N` ahead/behind) + +Select a branch and press Enter to switch. + +## Push, Pull & Fetch + +| Key | Action | +|-----|--------| +| `P` | Open push menu | +| `p` | Pull from remote | +| `f` | Fetch from remote | + +### Push Menu + +Three options when you press `P`: + +1. **Push**: Regular `git push -u origin HEAD` +2. **Force push**: `git push --force-with-lease` (safer force push) +3. **Push with upstream**: Sets tracking if not configured + +Quick shortcuts in the push menu: +- `p` - Quick push +- `f` - Quick force push +- `u` - Quick push with upstream + +### Push Status + +The commit sidebar shows: +- Commits ahead/behind upstream +- Per-commit pushed indicator +- Unpushed commit count + +## Stash Operations + +| Key | Action | +|-----|--------| +| `z` | Stash all changes | +| `Z` | Pop latest stash (with confirmation) | + +Pop shows a confirmation modal with stash details before applying. + +## Commit History + +The sidebar shows recent commits with infinite scroll. Navigate to load more. + +| Key | Action | +|-----|--------| +| `/` | Search commits | +| `n` | Next search match | +| `N` | Previous search match | +| `f` | Filter by author | +| `p` | Filter by file path | +| `F` | Clear all filters | +| `v` | Toggle commit graph | + +### Commit Search + +Search by commit subject or author name. Supports: +- Case-insensitive matching (default) +- Regex patterns (optional) +- Live-as-you-type results + +### Commit Graph + +Press `v` to toggle ASCII graph visualization showing branch history: + +``` +* abc123 Latest commit +* def456 Previous commit +|\ +| * ghi789 Feature branch +|/ +* jkl012 Merge base +``` + +### Commit Preview + +Select a commit to see: +- Full commit message +- Files changed with `+/-` stats +- Navigate files and view their diffs + +## Clipboard Operations + +| Key | Action | +|-----|--------| +| `y` | Copy commit as markdown | +| `Y` | Copy commit hash only | + +Markdown format includes subject, hash, author, date, stats, and file list. + +## GitHub Integration + +| Key | Action | +|-----|--------| +| `o` | Open commit in GitHub | + +Auto-detects repository from remote URL (SSH or HTTPS). + +## Navigation + +### File Tree + +| Key | Action | +|-----|--------| +| `j`, `↓` | Move down | +| `k`, `↑` | Move up | +| `g` | Jump to top | +| `G` | Jump to bottom | +| `enter` | Open file in editor / toggle folder | +| `O` | Open file in File Browser plugin | +| `l`, `→` | Focus diff pane | + +### Diff Pane + +| Key | Action | +|-----|--------| +| `j`, `↓` | Scroll down | +| `k`, `↑` | Scroll up | +| `ctrl+d` | Page down | +| `ctrl+u` | Page up | +| `g` | Jump to top | +| `G` | Jump to bottom | +| `h`, `←` | Focus sidebar / scroll left | + +### General + +| Key | Action | +|-----|--------| +| `tab` | Switch focus between panes | +| `\` | Toggle sidebar visibility | +| `r` | Refresh status | + +## Mouse Support + +- **Click file**: Select and show diff +- **Click commit**: Select and show preview +- **Click folder**: Expand/collapse +- **Drag divider**: Resize panes +- **Scroll**: Navigate lists and diffs + +## Real-Time Updates + +The plugin watches your `.git` directory and auto-refreshes when: +- Files change on disk +- Agent makes commits +- Branches switch +- Remote operations complete + +Debounced to prevent excessive refreshes (500ms minimum). + +## State Persistence + +These preferences save across sessions: +- Diff view mode (unified/side-by-side) +- Sidebar width +- Commit graph enabled/disabled + +## Command Reference + +All keyboard shortcuts by context: + +### Files Context (`git-status`) + +| Key | Action | +|-----|--------| +| `s` | Stage | +| `u` | Unstage | +| `S` | Stage all | +| `d` | Full diff | +| `D` | Discard | +| `c` | Commit | +| `b` | Branch picker | +| `P` | Push menu | +| `p` | Pull | +| `f` | Fetch | +| `z` | Stash | +| `Z` | Pop stash | +| `r` | Refresh | +| `O` | Open in file browser | +| `enter` | Open in editor | + +### Commits Context (`git-status-commits`) + +| Key | Action | +|-----|--------| +| `/` | Search | +| `n` | Next match | +| `N` | Previous match | +| `f` | Filter by author | +| `p` | Filter by path | +| `F` | Clear filters | +| `v` | Toggle graph | +| `y` | Copy markdown | +| `Y` | Copy hash | +| `o` | Open in GitHub | + +### Diff Context (`git-status-diff`, `git-diff`) + +| Key | Action | +|-----|--------| +| `v` | Toggle view mode | +| `h`, `←` | Scroll left | +| `l`, `→` | Scroll right | +| `0` | Reset scroll | +| `O` | Open in file browser | +| `esc`, `q` | Close | + +### Commit Modal (`git-commit`) + +| Key | Action | +|-----|--------| +| `ctrl+s` | Execute commit | +| `tab` | Switch focus | +| `esc` | Cancel | + +### Push Menu (`git-push-menu`) + +| Key | Action | +|-----|--------| +| `p` | Quick push | +| `f` | Quick force push | +| `u` | Push with upstream | +| `enter` | Execute selected | +| `esc`, `q` | Close | diff --git a/website/docs/intro.md b/website/docs/intro.md index 0587cf65..b697c72d 100644 --- a/website/docs/intro.md +++ b/website/docs/intro.md @@ -1,14 +1,13 @@ --- sidebar_position: 1 +title: Getting Started --- -# Introduction +# Sidecar -Sidecar is a terminal UI for monitoring AI coding agent sessions. +A terminal dashboard for AI coding agents. Monitor git changes, browse conversations, track tasks, and manage worktrees—all without leaving your terminal. -## Overview - -Sidecar provides a unified terminal interface for viewing Claude Code conversations, git status, and task progress. Built for developers who want visibility into their AI coding sessions without leaving the terminal. +![Sidecar Git Status](/img/screenshots/sidecar-git.png) ## Quick Install @@ -16,25 +15,159 @@ Sidecar provides a unified terminal interface for viewing Claude Code conversati curl -fsSL https://raw.githubusercontent.com/marcus/sidecar/main/scripts/setup.sh | bash ``` -## Requirements - -- Go 1.21+ -- macOS, Linux, or WSL +**Requirements:** macOS, Linux, or WSL. Go 1.21+ (for building from source). ## Quick Start -After installation, run from any project directory: +Run from any project directory: ```bash sidecar ``` -## Features +Sidecar automatically detects your git repo and any active AI agent sessions. + +### Suggested Setup + +Split your terminal: agent on the left, sidecar on the right. + +``` ++-----------------------------+---------------------+ +| | | +| Claude Code / Cursor | Sidecar | +| | | +| $ claude | [Git] [Files] | +| > fix the auth bug... | [TD] [Worktrees] | +| | | ++-----------------------------+---------------------+ +``` + +As the agent works, watch files change in Git Status, track tasks in TD Monitor, and browse code in File Browser. + +## Plugins + +Sidecar uses a plugin architecture. Each plugin provides a focused view into your development workflow. + +### Git Status + +Stage files, view diffs, browse commit history. A lightweight alternative to `git status` and `git diff`. + +![Git Status with Diff](/img/screenshots/sidecar-git.png) + +| Key | Action | +|-----|--------| +| `s` | Stage file | +| `u` | Unstage file | +| `d` | View diff (full-screen) | +| `v` | Toggle side-by-side diff | +| `c` | Commit staged changes | +| `h/l` | Switch sidebar/diff focus | + +![Side-by-side Diff](/img/screenshots/sidecar-git-diff-side-by-side.png) + +### Conversations + +Browse AI agent session history with message content, token usage, and search. + +![Conversations](/img/screenshots/sidecar-conversations.png) + +Supported agents: +- Claude Code +- Cursor +- Gemini CLI +- OpenCode +- Codex +- Warp + +| Key | Action | +|-----|--------| +| `/` | Search sessions | +| `enter` | Expand/collapse messages | +| `j/k` | Navigate sessions | + +### TD Monitor + +Integration with [TD](https://github.com/marcus/td), a task management system for AI agents working across context windows. + +![TD Monitor](/img/screenshots/sidecar-td.png) + +| Key | Action | +|-----|--------| +| `r` | Submit review | +| `enter` | View task details | + +### File Browser + +Navigate project files with a collapsible tree and syntax-highlighted preview. + +![File Browser](/img/screenshots/sidecar-file-browser.png) + +| Key | Action | +|-----|--------| +| `enter` | Open/close folder | +| `/` | Search files | +| `h/l` | Switch tree/preview focus | + +### Worktrees + +Manage git worktrees for parallel development. Create isolated branches, link tasks, and launch agents directly. + +| Key | Action | +|-----|--------| +| `n` | Create worktree | +| `D` | Delete worktree | +| `a` | Launch agent | +| `t` | Link TD task | +| `m` | Start merge workflow | + +## Navigation + +Global shortcuts work across all plugins: + +| Key | Action | +|-----|--------| +| `q`, `ctrl+c` | Quit | +| `tab` / `shift+tab` | Next/previous plugin | +| `1-5` | Focus plugin by number | +| `j/k`, `arrow keys` | Navigate items | +| `ctrl+d/u` | Page down/up | +| `g/G` | Jump to top/bottom | +| `?` | Toggle help | +| `r` | Refresh | + +## Configuration + +Config file: `~/.config/sidecar/config.json` + +```json +{ + "plugins": { + "git-status": { "enabled": true, "refreshInterval": "1s" }, + "td-monitor": { "enabled": true, "refreshInterval": "2s" }, + "conversations": { "enabled": true }, + "file-browser": { "enabled": true }, + "worktrees": { "enabled": true } + }, + "ui": { + "showFooter": true, + "showClock": true + } +} +``` + +## CLI Options + +```bash +sidecar # Run in current directory +sidecar --project /path # Specify project root +sidecar --debug # Enable debug logging +sidecar --version # Print version +``` + +## Updates + +Sidecar checks for updates on startup. When available, a notification appears. Press `!` to open diagnostics and see the update command. -- **Git Status** - View staged, modified, and untracked files with syntax-highlighted diffs -- **Conversations** - Browse Claude Code session history with message content and token usage -- **TD Monitor** - Integration with TD task management for AI agents -- **File Browser** - Navigate project files with tree view and preview -- **Worktrees** - Manage git worktrees for parallel development +## Source -For more details, see the [GitHub repository](https://github.com/marcus/sidecar). +[GitHub Repository](https://github.com/marcus/sidecar) diff --git a/website/docs/td.md b/website/docs/td.md new file mode 100644 index 00000000..e74de5f7 --- /dev/null +++ b/website/docs/td.md @@ -0,0 +1,301 @@ +--- +sidebar_position: 2 +title: TD - Task Management for AI Agents +--- + +# TD + +A task management CLI designed specifically for AI-assisted development. When an agent's context window ends, its memory ends. TD captures the work state—what's done, what's remaining, key decisions, and uncertainties—so the next session picks up exactly where the previous one left off. + +![TD Monitor in Sidecar](/img/screenshots/sidecar-td.png) + +## The Problem + +AI coding agents have a fundamental limitation: **context windows reset**. When a session ends, the agent forgets everything. This leads to: + +- **Hallucinated state**: Agents guess what's done vs. remaining +- **Lost decisions**: Why did we choose approach X over Y? +- **Repeated work**: Re-implementing things already completed +- **Broken handoffs**: No structured way to pass context between sessions + +TD solves this by providing **external memory** for AI agents—a local database that persists across context windows. + +## Quick Install + +```bash +go install github.com/marcus/td@latest +``` + +**Requirements:** Go 1.21+ + +## Quick Start + +Initialize TD in your project: + +```bash +td init +``` + +This creates a `.todos/` directory with a SQLite database. Add to `.gitignore` automatically. + +### For AI Agents (Claude Code, Cursor, etc.) + +Add this to your `CLAUDE.md` or agent instructions: + +```markdown +# Task Management + +Run at the start of every conversation: +td usage --new-session + +Before your context ends, ALWAYS run: +td handoff --done "..." --remaining "..." +``` + +## Core Concepts + +### Sessions + +Every terminal or AI agent gets a unique session ID. Sessions are scoped by **git branch + agent type**, so the same agent on the same branch maintains consistent identity. + +```bash +td whoami # Show current session +td usage --new-session # Start fresh session, see current state +``` + +TD auto-detects agent type: Claude Code, Cursor, Copilot, or manual terminal. + +### Issues + +Create structured work items with type and priority: + +```bash +td create "Implement OAuth2 authentication flow" --type feature --priority P1 +``` + +Issue types: `feature`, `bug`, `chore`, `docs`, `refactor`, `test` + +Priorities: `P0` (critical), `P1` (high), `P2` (medium), `P3` (low) + +### Lifecycle + +Issues follow a state machine with enforced transitions: + +``` +open → in_progress → in_review → closed + ↓ ↑ + blocked ──────────┘ (reject) +``` + +Key constraint: **The session that implements code cannot approve it.** This ensures a different context (human or another agent session) reviews the work. + +## CLI Commands + +### Working on Issues + +```bash +td start # Begin work (moves to in_progress) +td log "message" # Track progress +td log --decision "..." # Log a decision with reasoning +td log --blocker "..." # Log a blocker +td handoff \ # Capture state for next session + --done "OAuth flow working" \ + --remaining "Token refresh, error handling" \ + --decision "Using JWT for stateless auth" \ + --uncertain "Should tokens expire on password change?" +``` + +### Review Workflow + +```bash +td review # Submit for review (moves to in_review) +td reviewable # List issues you can review +td context # See full handoff state +td approve # Approve and close (different session required) +td reject --reason "..." # Reject back to in_progress +``` + +### Querying Issues + +```bash +td list # All open issues +td list --status in_progress # Filter by status +td next # Highest priority open issue +td show # Full issue details +td search "keyword" # Full-text search +``` + +### TDQ Query Language + +Powerful expressions for filtering: + +```bash +td query "status = in_progress AND priority <= P1" +td query "type = bug AND labels ~ auth" +td query "assignee = @me AND created >= -7d" +td query "rework()" # Issues rejected, needing fixes +td query "stale(14)" # No updates in 14 days +``` + +Operators: `=`, `!=`, `~` (contains), `<`, `>`, `<=`, `>=`, `AND`, `OR`, `NOT` + +### Dependencies + +Model relationships between issues: + +```bash +td dep add # Issue depends on another +td dep rm # Remove dependency +td dep # Show what this depends on +td blocked-by # Show all transitively blocked +td critical-path # Optimal work sequence +``` + +### File Tracking + +Link files to issues to track what changed: + +```bash +td link src/auth/*.go # Link files (records SHA) +td files # Show status: [modified], [unchanged], [new] +``` + +### Boards + +Organize issues with query-based boards: + +```bash +td board create "Sprint 1" --query "labels ~ sprint-1" +td board list +td board show +``` + +## Multi-Issue Work Sessions + +When tackling multiple related issues: + +```bash +td ws start "Auth implementation" # Start work session +td ws tag td-a1b2 td-c3d4 # Associate issues (auto-starts them) +td ws log "Shared token storage" # Log to all tagged issues +td ws handoff # Capture state for all, end session +``` + +## Structured Handoffs + +The handoff is the most important command. It captures everything the next session needs: + +```bash +td handoff td-a1b2 \ + --done "OAuth callback endpoint, token storage, login UI" \ + --remaining "Refresh token rotation, logout endpoint, error states" \ + --decision "Using httpOnly cookies instead of localStorage for tokens - more secure against XSS" \ + --uncertain "Should we support multiple active sessions per user?" +``` + +Each field serves a purpose: + +| Field | Purpose | +|-------|---------| +| `--done` | What's actually complete and tested | +| `--remaining` | Specific tasks left (not vague "finish it") | +| `--decision` | Why you chose this approach (prevents re-litigation) | +| `--uncertain` | Questions for the next session or human review | + +## Workflow Examples + +### Single Issue (Typical) + +```bash +# Session 1: Start work +td start td-a1b2 +td log "Set up OAuth provider config" +td log --decision "Using Auth0 - better docs than Okta" +td handoff td-a1b2 --done "Provider setup" --remaining "Callback handling" + +# Session 2: Continue +td usage --new-session # See where we left off +td start td-a1b2 # Resume +td log "Implemented callback endpoint" +td review td-a1b2 # Submit for review + +# Session 3 (different): Review +td reviewable # See pending reviews +td context td-a1b2 # Read full handoff +td approve td-a1b2 # Close it +``` + +### Bug Fix with Context + +```bash +td create "Login fails silently on expired tokens" --type bug --priority P1 +td start td-xyz123 +td log "Reproduced: token refresh race condition" +td log --decision "Adding mutex around token refresh" +td link td-xyz123 src/auth/refresh.go +td handoff td-xyz123 \ + --done "Root cause identified, fix implemented" \ + --remaining "Add regression test" \ + --uncertain "Should we add retry logic for network failures?" +``` + +### Parallel Work with Worktrees + +Combined with Sidecar's worktree management: + +1. Create worktree in Sidecar (`n`) +2. Link TD task (`t`) +3. Agent works with TD tracking progress +4. Handoff before context ends +5. Review in separate session/worktree + +## Live Monitor + +Run the interactive TUI dashboard: + +```bash +td monitor +``` + +Features: +- Real-time task visualization +- Board view with swimlanes +- Search and filtering +- Statistics modal +- Keyboard navigation + +Or use Sidecar's TD Monitor plugin for integrated viewing. + +## Configuration + +TD is zero-config by default. Optional environment variables: + +| Variable | Purpose | +|----------|---------| +| `TD_SESSION_ID` | Force specific session ID | +| `TD_ANALYTICS` | Set to `false` to disable usage analytics | + +## Data Storage + +All data lives in `.todos/db.sqlite`—a local SQLite database. No external services, no sync, no accounts. + +``` +.todos/ +├── db.sqlite # All issues, logs, handoffs +└── sessions/ # Session tracking per branch +``` + +## Integration with Sidecar + +Sidecar's TD Monitor plugin provides a visual dashboard for TD: + +- See all issues at a glance +- Submit reviews directly (`r`) +- View issue details (`enter`) +- Real-time refresh + +![TD in Sidecar](/img/screenshots/sidecar-td2.png) + +## Source + +[GitHub Repository](https://github.com/marcus/td) diff --git a/website/docs/worktrees-plugin.md b/website/docs/worktrees-plugin.md new file mode 100644 index 00000000..000493a8 --- /dev/null +++ b/website/docs/worktrees-plugin.md @@ -0,0 +1,336 @@ +--- +sidebar_position: 6 +title: Worktrees Plugin +--- + +# Worktrees Plugin + +Manage multiple git worktrees with agent integration, real-time output streaming, and a Kanban board view—run parallel agents across branches. + +## Overview + +The Worktrees plugin provides a two-pane layout: + +- **Left pane**: Worktree list (or Kanban columns) +- **Right pane**: Preview tabs (Output, Diff, Task) +- **Draggable divider**: Resize panes to your preference + +Toggle views with `v` for list or Kanban board. + +## View Modes + +### List View + +Vertical list of all worktrees with status indicators: + +| Status | Meaning | +|--------|---------| +| Active | Agent running | +| Waiting | Agent needs approval | +| Done | Work completed | +| Paused | Agent stopped | +| Error | Something failed | + +### Kanban View + +Press `v` to switch to Kanban board with columns: +- **Active**: Agents currently working +- **Waiting**: Agents needing approval +- **Done**: Completed work +- **Paused**: Stopped agents + +Each column shows worktree count. + +## Worktree Navigation + +| Key | Action | +|-----|--------| +| `j`, `↓` | Move down | +| `k`, `↑` | Move up | +| `g` | Jump to first | +| `G` | Jump to last | +| `h`, `←` | Previous column (Kanban) | +| `l`, `→` | Next column (Kanban) or focus preview | +| `v` | Toggle list/Kanban view | + +## Preview Tabs + +Three tabs in the preview pane: + +| Key | Action | +|-----|--------| +| `[` | Previous tab | +| `]` | Next tab | + +### Output Tab + +Real-time agent output streaming: + +| Key | Action | +|-----|--------| +| `j`, `↓` | Scroll down (pauses auto-scroll) | +| `k`, `↑` | Scroll up | +| `ctrl+d` | Page down | +| `ctrl+u` | Page up | +| `g` | Jump to top | +| `G` | Jump to bottom (resumes auto-scroll) | + +Auto-scroll follows new output by default. Manual scrolling pauses it; pressing `G` or `j` at the bottom resumes. + +### Diff Tab + +Git diff for the worktree branch: + +| Key | Action | +|-----|--------| +| `v` | Toggle unified/side-by-side view | +| `h`, `←` | Scroll left (wide diffs) | +| `l`, `→` | Scroll right | +| `0` | Reset horizontal scroll | + +Shows merge conflicts when present. + +### Task Tab + +Linked TD task details with markdown rendering: + +| Key | Action | +|-----|--------| +| `m` | Toggle markdown rendering | +| `j`, `↓` | Scroll down | +| `k`, `↑` | Scroll up | + +## Agent Management + +Start, stop, and control coding agents from any worktree. + +### Starting Agents + +| Key | Action | +|-----|--------| +| `s` | Start agent | + +If no agent is running, opens a choice modal: +- Claude +- Codex +- Gemini +- Cursor +- OpenCode +- Aider + +### Attaching to Agents + +| Key | Action | +|-----|--------| +| `enter` | Attach to running agent | + +Opens the agent's terminal session for direct interaction. + +### Agent Controls + +| Key | Action | +|-----|--------| +| `S` | Stop agent | +| `y` | Approve pending action | +| `Y` | Approve all pending prompts | +| `N` | Reject pending action | + +The approval workflow handles agents in "Waiting" status that need permission to proceed. + +## Worktree Operations + +### Creating Worktrees + +Press `n` to open the create modal: + +| Field | Description | +|-------|-------------| +| Name | Worktree branch name | +| Base branch | Branch to create from | +| Prompt | Initial agent prompt | +| Task | Link to TD task (optional) | +| Agent | Which agent to start | +| Skip perms | Skip permission prompts | + +Modal navigation: + +| Key | Action | +|-----|--------| +| `tab` | Next field | +| `shift+tab` | Previous field | +| `j`, `↓` | Navigate dropdowns | +| `k`, `↑` | Navigate dropdowns | +| `enter` | Select or confirm | +| `esc` | Cancel | + +### Deleting Worktrees + +| Key | Action | +|-----|--------| +| `D` | Delete worktree | + +Opens confirmation with options: +- Delete local branch +- Delete remote branch + +| Key | Action | +|-----|--------| +| `j`, `↓` | Navigate options | +| `space` | Toggle checkbox | +| `enter` | Confirm | +| `D` | Quick delete (power user) | +| `esc` | Cancel | + +### Push & Remote + +| Key | Action | +|-----|--------| +| `p` | Push branch to remote | + +## Task Linking + +Link worktrees to TD tasks for context: + +| Key | Action | +|-----|--------| +| `t` | Link/unlink TD task | + +Opens task picker to select from open tasks. + +## Merge Workflow + +Press `m` to start a multi-step merge: + +1. **Diff review**: See changes to be merged +2. **Method selection**: Choose merge strategy (merge, squash, rebase) +3. **PR creation**: Wait for PR to be created +4. **Cleanup options**: Delete branches after merge + +| Key | Action | +|-----|--------| +| `j`, `↓` | Navigate options | +| `enter` | Proceed to next step | +| `space` | Toggle checkboxes | +| `tab` | Cycle focus | +| `s` | Skip step (for pushed branches) | +| `esc`, `q` | Cancel merge | + +## Pane Navigation + +| Key | Action | +|-----|--------| +| `tab` | Switch to next pane | +| `shift+tab` | Switch to previous pane | +| `l`, `→` | Focus preview pane | +| `h`, `←` | Focus sidebar | +| `enter` | Focus preview (from list) | +| `esc` | Return to sidebar | +| `\` | Toggle sidebar visibility | + +## Mouse Support + +- **Click worktree**: Select +- **Click tab**: Switch preview tab +- **Click button**: Execute action +- **Drag divider**: Resize panes +- **Scroll**: Navigate lists and content + +## State Persistence + +These preferences save across sessions: +- View mode (list/Kanban) +- Sidebar width +- Diff view mode (unified/side-by-side) +- Active tab + +## Command Reference + +All keyboard shortcuts by context: + +### Sidebar Context (`worktree-sidebar`) + +| Key | Action | +|-----|--------| +| `j`, `↓` | Move down | +| `k`, `↑` | Move up | +| `g` | Jump to top | +| `G` | Jump to bottom | +| `h`, `←` | Previous column (Kanban) | +| `l`, `→` | Next column / focus preview | +| `v` | Toggle view mode | +| `n` | Create worktree | +| `D` | Delete worktree | +| `p` | Push branch | +| `d` | Show diff | +| `m` | Merge workflow | +| `t` | Link task | +| `s` | Start agent | +| `S` | Stop agent | +| `y` | Approve action | +| `Y` | Approve all | +| `N` | Reject action | +| `enter` | Attach to agent | +| `[` | Previous tab | +| `]` | Next tab | +| `tab` | Focus preview | +| `\` | Toggle sidebar | + +### Preview Context (`worktree-preview`) + +| Key | Action | +|-----|--------| +| `j`, `↓` | Scroll down | +| `k`, `↑` | Scroll up | +| `ctrl+d` | Page down | +| `ctrl+u` | Page up | +| `g` | Jump to top | +| `G` | Jump to bottom | +| `v` | Toggle diff view (diff tab) | +| `h`, `←` | Scroll left / focus sidebar | +| `l`, `→` | Scroll right | +| `0` | Reset scroll | +| `m` | Toggle markdown (task tab) | +| `s` | Start agent | +| `S` | Stop agent | +| `y` | Approve action | +| `Y` | Approve all | +| `N` | Reject action | +| `[` | Previous tab | +| `]` | Next tab | +| `tab` | Focus sidebar | +| `esc` | Focus sidebar | +| `\` | Toggle sidebar | + +### Create Modal (`worktree-create`) + +| Key | Action | +|-----|--------| +| `tab` | Next field | +| `shift+tab` | Previous field | +| `j`, `↓` | Navigate dropdown | +| `k`, `↑` | Navigate dropdown | +| `enter` | Select / confirm | +| `esc` | Cancel | + +### Merge Modal (`worktree-merge`) + +| Key | Action | +|-----|--------| +| `j`, `↓` | Navigate options | +| `k`, `↑` | Navigate options | +| `enter` | Proceed | +| `space` | Toggle checkbox | +| `tab` | Cycle focus | +| `s` | Skip step | +| `esc`, `q` | Cancel | + +### Delete Modal (`worktree-delete`) + +| Key | Action | +|-----|--------| +| `j`, `↓` | Navigate options | +| `k`, `↑` | Navigate options | +| `space` | Toggle checkbox | +| `enter` | Confirm | +| `D` | Quick delete | +| `esc`, `q` | Cancel | diff --git a/website/src/css/custom.css b/website/src/css/custom.css index 667ff41e..620bdf84 100644 --- a/website/src/css/custom.css +++ b/website/src/css/custom.css @@ -81,6 +81,31 @@ html[data-theme="dark"] .navbar__brand { letter-spacing: 0.2px; } +/* Terminal green logo with pulsing prompt */ +html[data-theme="dark"] .navbar__title { + color: #00b33c; + text-shadow: 0 0 8px rgba(0, 179, 60, 0.5), 0 0 16px rgba(0, 179, 60, 0.3); + font-family: var(--ifm-font-family-monospace); +} + +html[data-theme="dark"] .navbar__title::after { + content: " >"; + color: #00b33c; + text-shadow: 0 0 8px rgba(0, 179, 60, 0.5), 0 0 16px rgba(0, 179, 60, 0.3); + animation: promptPulse 2s ease-in-out infinite; +} + +@keyframes promptPulse { + 0%, 100% { + opacity: 1; + text-shadow: 0 0 8px rgba(0, 179, 60, 0.5), 0 0 16px rgba(0, 179, 60, 0.3); + } + 50% { + opacity: 0.5; + text-shadow: 0 0 4px rgba(0, 179, 60, 0.3), 0 0 8px rgba(0, 179, 60, 0.15); + } +} + html[data-theme="dark"] .footer { border-top: 1px solid var(--sc-border); background: #0f1114; @@ -93,11 +118,14 @@ html[data-theme="dark"]::before { inset: 0; z-index: -1; background: - radial-gradient(ellipse 1200px 600px at 15% 5%, rgba(249, 38, 114, 0.12), transparent 50%), - radial-gradient(ellipse 1200px 600px at 85% 8%, rgba(102, 217, 239, 0.10), transparent 50%), - radial-gradient(ellipse 1400px 800px at 50% 40%, rgba(166, 226, 46, 0.06), transparent 50%), - radial-gradient(ellipse 1200px 600px at 20% 70%, rgba(174, 129, 255, 0.08), transparent 50%), - radial-gradient(ellipse 1200px 600px at 80% 90%, rgba(230, 219, 116, 0.06), transparent 50%); + radial-gradient(ellipse 80vw 50vh at 15% 5%, rgba(249, 38, 114, 0.12), transparent 50%), + radial-gradient(ellipse 80vw 50vh at 85% 8%, rgba(102, 217, 239, 0.10), transparent 50%), + radial-gradient(ellipse 90vw 60vh at 50% 40%, rgba(166, 226, 46, 0.06), transparent 50%), + radial-gradient(ellipse 80vw 50vh at 20% 70%, rgba(174, 129, 255, 0.08), transparent 50%), + radial-gradient(ellipse 80vw 50vh at 80% 90%, rgba(230, 219, 116, 0.06), transparent 50%); + background-size: 100vw 100vh; + background-repeat: no-repeat; + background-attachment: fixed; pointer-events: none; } @@ -171,7 +199,15 @@ a:hover { } .sc-titleBrand { - color: var(--ifm-color-primary); + color: #00b33c; + text-shadow: 0 0 10px rgba(0, 179, 60, 0.5), 0 0 20px rgba(0, 179, 60, 0.3), 0 0 30px rgba(0, 179, 60, 0.2); +} + +.sc-titleBrand::after { + content: " >"; + color: #00b33c; + text-shadow: 0 0 10px rgba(0, 179, 60, 0.5), 0 0 20px rgba(0, 179, 60, 0.3); + animation: promptPulse 2s ease-in-out infinite; } .sc-titleTagline { diff --git a/website/static/img/screenshots/sidecar-conversations.png b/website/static/img/screenshots/sidecar-conversations.png new file mode 100644 index 00000000..982e4cd0 Binary files /dev/null and b/website/static/img/screenshots/sidecar-conversations.png differ diff --git a/website/static/img/screenshots/sidecar-file-browser.png b/website/static/img/screenshots/sidecar-file-browser.png new file mode 100644 index 00000000..ea3c295e Binary files /dev/null and b/website/static/img/screenshots/sidecar-file-browser.png differ diff --git a/website/static/img/screenshots/sidecar-git-diff-side-by-side.png b/website/static/img/screenshots/sidecar-git-diff-side-by-side.png new file mode 100644 index 00000000..170a6c51 Binary files /dev/null and b/website/static/img/screenshots/sidecar-git-diff-side-by-side.png differ diff --git a/website/static/img/screenshots/sidecar-git.png b/website/static/img/screenshots/sidecar-git.png new file mode 100644 index 00000000..624d36d7 Binary files /dev/null and b/website/static/img/screenshots/sidecar-git.png differ diff --git a/website/static/img/screenshots/sidecar-riders.png b/website/static/img/screenshots/sidecar-riders.png new file mode 100644 index 00000000..0dc18351 Binary files /dev/null and b/website/static/img/screenshots/sidecar-riders.png differ diff --git a/website/static/img/screenshots/sidecar-td.png b/website/static/img/screenshots/sidecar-td.png new file mode 100644 index 00000000..db144abb Binary files /dev/null and b/website/static/img/screenshots/sidecar-td.png differ diff --git a/website/static/img/screenshots/sidecar-td2.png b/website/static/img/screenshots/sidecar-td2.png new file mode 100644 index 00000000..c86c6076 Binary files /dev/null and b/website/static/img/screenshots/sidecar-td2.png differ