Development
Plugin
sidecar
You might never open your editor again. Status: Ready for daily use. Please report any issues you encounter.
Plugin Signal83/100Strong
maintained100
capable60
documented100
adopted64
Install
$ npx -y skills add marcus/sidecar --agent claude-code
Run the curl in your terminal, the rest in Claude Code.
What's inside
Skills
17/create-adapterCreate conversation adapters for importing AI chat history from different tools (Claude Code, Cursor, Warp, Codex, etc.). Covers the adapter.Adapter interface, caching strategies, incremental parsing, watch/FD management, and performance standards. Use when creating a new/create-modalCreate declarative modals using the modal library API. Covers modal types (confirm, input, select, form), sections (Text, Buttons, Input, Textarea, Checkbox, List, When, Custom), rendering with OverlayModal, and keyboard/mouse handling. Use when adding modals or dialogs to the/create-pluginCreate new sidecar plugins implementing the plugin.Plugin interface, rendering views with Bubble Tea, handling keyboard input via keymap contexts, and integrating with the app shell (footer hints, event bus, adapters). Use when creating a new plugin, modifying plugin/create-promptCreate prompts for sidecar workspaces. Covers prompt structure (name, ticketMode, body), template variables (ticket with fallbacks), config file locations (global vs project), and scope overrides. Use when creating or modifying prompts in sidecar config files./create-themeCreate custom color themes for Sidecar, including base theme selection, color overrides, gradient borders, tab styles, per-project themes, community themes, and programmatic theme registration. Use when creating or modifying themes, adjusting UI appearance, or debugging/drag-paneDrag-and-drop pane resizing implementation for two-pane plugin layouts. Covers mouse event handling via the internal/mouse package, hit region registration, drag delta calculation, width clamping, state persistence, and pane layout management. Use when working on pane resizing,
Show all 17 skillsShow fewer
/feature-flagsCreating and using feature flags in sidecar for gating experimental functionality. Covers flag registration, checking flags in code, config file and CLI overrides, and priority resolution. Use when adding feature flags, toggling features, or gating new functionality behind flags./inline-editorInline text editing implementation within the file browser preview pane using tmux PTY backend, cursor movement, text manipulation, and editor state management. Covers entry/exit lifecycle, dimension calculations, confirmation dialogs, click-away detection, mouse forwarding, and/keyboard-shortcutsReference for keyboard shortcut implementation, keybinding registration, shortcut parity with vim and other TUI tools, and the complete shortcut assignment table across all sidecar plugins. Use when adding or modifying keyboard shortcuts, checking shortcut assignments, resolving/merge-strategyGit merge strategies, conflict resolution approaches, merge vs rebase recommendations, and branch integration patterns in sidecar. Covers pull strategy menu, direct merge workflow, squash merge, commit message templates, configurable defaults, and protected branches. Use when/profile-memoryProfile memory usage in sidecar using Go pprof, system tools, and heap analysis. Covers identifying memory leaks, goroutine leaks, file descriptor accumulation, and CPU profiling. Use when investigating memory issues, profiling performance, debugging memory leaks, or diagnosing/project-switchingProject switching implementation in sidecar: project discovery, state management, UI flow, modal rendering, filtering, theme preview, and plugin reinitialization. Use when working on the project switcher feature, project management, worktree switching, or the project/release-sidecarRelease new versions of sidecar. Covers version tagging with semver, td dependency updates, go.mod validation, CHANGELOG updates, GoReleaser automation, Homebrew tap updates, and verification steps. Use when preparing or executing a release./shell-integrationInteractive shell/TTY integration with tmux session management, shell command execution, control-mode output capture with polling fallback, native cursor rendering, lazy scrollback, selection, paste handling, and inline editing. Use when working on shell integration, tmux/sidecar-websiteWriting and maintaining the Sidecar Docusaurus documentation site, including page structure, doc authoring, blog posts, styling, images, and deployment workflow. Use when writing documentation, updating the docs site, adding pages or blog posts, or working with Docusaurus/ui-featuresImplementing UI/UX features in sidecar including modals (internal/modal library), keyboard shortcuts, mouse support, scrolling, pill/tab rendering, and pane resizing. Use when implementing UI features, handling user input, adding keyboard shortcuts, building modals, or working/worktree-switchingGit worktree support in sidecar: worktree detection, switching between worktrees, worktree state management, and plugin reinitialization. Covers the full lifecycle of worktree context switching including registry reinit, per-worktree state persistence, deleted worktree detection
README
1Sidecar
You might never open your editor again.
Status: Ready for daily use. Please report any issues you encounter.
Documentation · Getting Started
Overview
Sidecar puts your entire development workflow in one shell: plan tasks with td, chat with AI agents, review diffs, stage commits, review past conversations, and manage workspaces—all without leaving Sidecar.
Quick Install
macOS (recommended)
brew install marcus/tap/sidecar
This builds from source and avoids macOS Gatekeeper warnings.
Linux / Other
curl -fsSL https://raw.githubusercontent.com/marcus/sidecar/main/scripts/setup.sh | bash
More options: Binary downloads · Manual install
Requirements
- macOS, Linux, or WSL
- Go 1.21+ (only if building from source)
Quick Start
After installation, run from any project directory:
sidecar
Suggested Use
Split your terminal horizontally: run your coding agent (Claude Code, Cursor, etc.) on the left and sidecar on the right.
┌─────────────────────────────┬─────────────────────┐
│ │ │
│ Claude Code / Cursor │ Sidecar │
│ │ │
│ $ claude │ [Git] [Files] │
│ > fix the auth bug... │ [Tasks] [Workspaces]│
│ │ │
└─────────────────────────────┴─────────────────────┘
Tip: You can run two sidecar instances side-by-side to create a dashboard view. For example, keep one on the [Tasks] plugin and the other on [Git] or [Workspaces] to monitor everything at once.
As the agent works, you can:
- Watch tasks move through the workflow in TD Monitor
- See files change in real-time in the Git plugin
- Browse and edit code yourself in the File Browser
- View and resume conversations across all supported agent adapters
- Switch between built-in and community themes with live previews
This setup gives you visibility into what the agent is doing without interrupting your workflow. The entire dev loop—planning, monitoring, reviewing, committing—happens in the terminal while agents write the code.
Usage
# Run from any project directory
sidecar
# Specify project root
sidecar --project /path/to/project
# Enable debug logging
sidecar --debug
# Check version
sidecar --version
Updates
Sidecar checks for updates on startup. When a new version is available, a toast notification appears. Press ! to open the diagnostics modal and see the update command.
Plugins
Git Status
View staged, modified, and untracked files with a split-pane interface. The sidebar shows files and recent commits; the main pane shows syntax-highlighted diffs. Full documentation →
Features:
- Stage/unstage files with
s/u - View diffs inline or full-screen with
d - Toggle side-by-side diff view with
v - Browse commit history and view commit diffs
- Auto-refresh on file system changes
Conversations
Browse session history from multiple AI coding agents with message content, token usage, and search. Supports Amp Code, Claude Code, Codex, Cursor CLI, Gemini CLI, GitHub Copilot CLI, Kiro, OpenCode, Pi Agent, and Warp. Full documentation →
Features:
- Unified view across all supported agents
- View all sessions grouped by date
- Search sessions with
/ - Expand messages to see full content
- Track token usage per session
TD Monitor
Integration with TD, a task management system designed for AI agents working across context windows. TD helps agents track work, log progress, and maintain context across sessions—essential for AI-assisted development where context windows reset between conversations. Full documentation →
Features:
- Current focused task display
- Scrollable task list with status indicators
- Activity log with session context
- Quick review submission with
r
See the TD repository for installation and CLI usage.
File Browser
Navigate project files with a tree view and syntax-highlighted preview. Full documentation →
Features:
- Collapsible directory tree
- Code preview with syntax highlighting
- Auto-refresh on file changes
Workspaces
Manage workspaces for parallel development with integrated agent support. Create isolated branches as sibling directories, link tasks from TD, and launch coding agents directly from sidecar. Full documentation →
Features:
- Create and delete workspaces with
n/D - Link TD tasks to workspaces for context tracking
- Launch coding agents (Claude, Codex, Gemini, Cursor, OpenCode, Pi) with
a - Merge workflow: commit, push, create PR, and cleanup with
m - Auto-adds sidecar state files to .gitignore
- Preview diffs and task details in split-pane view
Project Switcher
Press @ to switch between configured projects without restarting sidecar.
- Add projects to
~/.config/sidecar/config.json:
{
"projects": {
"list": [
{ "name": "sidecar", "path": "~/code/sidecar" },
{ "name": "td", "path": "~/code/td" },
{ "name": "my-app", "path": "~/projects/my-app" }
]
}
}
- Press
@to open the project switcher modal - Select with
j/kor click, pressEnterto switch
All plugins reinitialize with the new project context. State (active plugin, cursor positions) is remembered per project.
Worktree Switcher
Press W to switch between git worktrees within the current repository. When you switch away from a project and return later, sidecar remembers which worktree you were working in and restores it automatically.
Themes
Press # to open the theme switcher. Choose from built-in themes (default, dracula) or press Tab to browse 453 community color schemes derived from iTerm2-Color-Schemes.
The community browser supports search filtering, live preview as you navigate, and color swatches for each scheme. Press Enter to save a scheme as your active theme.
See Theme Creation Skill for custom theme creation and color palette reference.
Keyboard Shortcuts
| Key | Action |
|---|---|
q, ctrl+c | Quit |
@ | Open project switcher |
W | Open worktree switcher |
# | Open theme switcher |
i | Open issue |
tab / shift+tab | Navigate plugins |
1-9 | Focus plugin by number |
j/k, ↓/↑ | Navigate items |
ctrl+d/u | Page down/up in scrollable views |
g/G | Jump to top/bottom |
enter | Select |
esc | Back/close |
r | Refresh |
? | Toggle help |
Git Status Shortcuts
| Key | Action |
|---|---|
s | Stage file |
u | Unstage file |
d | View diff (full-screen) |
v | Toggle side-by-side diff |
h/l | Switch sidebar/diff focus |
c | Commit staged changes |
Workspace Shortcuts
| Key | Action |
|---|---|
n | Create new workspace |
D | Delete workspace |
a | Launch/attach agent |
t | Link/unlink TD task |
m | Start merge workflow |
p | Push branch |
o | Open in finder/terminal |
Configuration
Config file: ~/.config/sidecar/config.json
{
"plugins": {
"git-status": { "enabled": true, "refreshInterval": "1s" },
"td-monitor": { "enabled": true, "refreshInterval": "2s" },
"conversations": { "enabled": true },
"file-browser": { "enabled": true },
"workspaces": { "enabled": true }
},
"ui": {
"showClock": true,
"terminalTitle": "{project}{worktree}",
"theme": {
"name": "default",
"overrides": {}
}
}
}
terminalTitle names the terminal window/tab after the active project — handy when several
sidecars are open at once. Variables: {project}, {worktree}, {plugin}, {dir}; set it
to "" to leave the title alone.
Contributing
- Bug reports: Open an issue
- Feature requests: Check the Sidecar Roadmap for planned features and backlog
Development
make build # Build to ./bin/sidecar
make test # Run Go tests
make test-dev-install # Test managed install switching in an isolated fake prefix
make test-v # Verbose Go test output
make install-local # Activate the canonical main checkout
make install-worktree # Deliberately activate the current branch/worktree
make install-status # Show managed link plus current/login shell resolution
make use-homebrew # Restore the installed Homebrew release
make install # Unmanaged go install to GOBIN (does not change Homebrew)
make fmt # Format code
make fmt-check # Verify formatting for changed Go files
make fmt-check-all # Verify formatting across full codebase
make lint # Lint new issues only (merge-base with main)
make lint-all # Lint entire codebase (includes legacy debt)
make install-hooks # Install pre-commit hooks (gofmt, go vet, go build)
make install-local refuses branches and linked worktrees so an incidental
checkout cannot silently replace the normal development binary. Use
make install-worktree when that replacement is intentional. Both managed
commands require Homebrew; use make install for a separate, unmanaged Go
installation.
Go Lint Baseline
- Formatting: changed Go files must be
gofmt-clean (make fmt-check) - Correctness lint:
errcheck,govet,ineffassign,staticcheck,unused - Enforcement: CI runs tests and blocks new lint issues on PRs (
.github/workflows/go-ci.yml) - Debt tracking: run
make lint-allto measure and burn down legacy lint debt
Privacy
Sidecar runs locally and makes no telemetry, analytics, or tracking requests. The only network calls are GitHub API version checks on startup (cached for 3 hours) and user-initiated changelog fetches. See PRIVACY.md for full details on data access, file reads/writes, and network behavior.
License
MIT
File tree
960marcus/sidecarView on GitHub
.claude/
settings.local.json
skills/
create-adapter/
references/
cursor-db-format.md
warp-sqlite-schema.md
SKILL.md
create-modal/
references/
complete-example.md
SKILL.md
create-plugin/
references/
fixed-footer-layout-guide.md
sidebar-list-guide.md
SKILL.md
create-prompt/
SKILL.md
create-theme/
SKILL.md
drag-pane/
SKILL.md
feature-flags/
SKILL.md
inline-editor/
SKILL.md
keyboard-shortcuts/
references/
assessment.md
SKILL.md
merge-strategy/
SKILL.md
profile-memory/
SKILL.md
project-switching/
references/
implementation-details.md
SKILL.md
release-sidecar/
SKILL.md
shell-integration/
references/
tmux-notes.md
SKILL.md
sidecar-website/
references/
site-configuration.md
SKILL.md
ui-features/
references/
keyboard-shortcuts-reference.md
SKILL.md
worktree-switching/
SKILL.md
.codex/
skills
.github/
workflows/
deploy-docs.yml
go-ci.yml
release.yml
test-docs.yml
.gitignore
.golangci.yml
.goreleaser.yml
.kiro/
settings/
lsp.json
AGENTS.md
CHANGELOG.md
cmd/
sidecar/
doc.go
main_test.go
main.go
configs/
default.json
docs/
guides/
active/
getting-started.md
git-performance-proof.md
headless-testing.md
releasing.md
worktree-creation.md
deprecated/
adapter-creator-guide.md
agent-orchestration-guide.md
capturing-screenshots.md
creating-prompts.md
cursor-db-format-guide.md
declarative-modal-guide.md
docusaurus-site-guide.md
drag-pane-implementation-guide.md
feature-flags.md
fixed-footer-layout-guide.md
inline-editor-implementation.md
interactive-shell-implementation.md
keyboard-shortcuts-assessment.md
keyboard-shortcuts-reference.md
memory-profiling.md
merge-strategy-recommendations.md
modal-creator-guide.md
mouse-support-guide.md
project-switcher-dev-guide.md
project-switching-guide.md
sidebar-list-guide.md
sidecar-keyboard-shortcuts-guide.md
sidecar-plugin-guide.md
theme-creator-guide.md
tmux-notes.md
ui-feature-guide.md
warp-sqlite-schema-guide.md
worktree-switching-guide.md
README.md
plans/
active/
cross-project-overview.md
td-64c916-byte-fed-tmux-screen-model.md
td-94e749-byte-screen-cutover.md
td-d240af-grok-conversations-adapter.md
workspace-tiling-plan.md
deprecated/
agent-orchestration-integration.md
agent-orchestration-sequence.md
agent-orchestration-sequence.png
cross-project-vision.md
modal-inventory-and-conformity.md
plan-files-plugin-responsiveness.md
spec-breadcrumb-navigation.md
spec-images-in-files-plugin.md
spec-td-monitor-plugin.md
hold/
openclaw-adapter-spec.md
implemented/
charm-upgrade-00-overview.md
charm-upgrade-01-xansi-warmup.md
charm-upgrade-02-lipgloss.md
charm-upgrade-03-bubbletea.md
charm-upgrade-04-bubbles.md
charm-upgrade-05-glamour.md
charm-upgrade-06-cellbuf.md
cursor-cli-adapter.md
embedded-terminal-audit.md
embedded-terminal-transport-decisions.md
fix-122-self-update-prompt.md
git-push-status.md
gradient-borders-implementation.md
modal-conversion-tracker.md
spec-auto-update.md
spec-claude-code-conversations.md
spec-conversations-improvements.md
spec-easy-setup.md
spec-file-browser-plugin.md
spec-gemini-adapter.md
spec-git-commit.md
spec-git-diff.md
spec-keyboard-shortcuts-improvement-part-two.md
spec-markdown-conversation-adapters.md
spec-memory-leak-analysis.md
spec-modal-library.md
spec-mouse-support.md
spec-omega.md
spec-per-project-themes.md
spec-project-search.md
spec-project-shell.md
spec-rename-move-ux.md
spec-td-monitor-plugin-wrapped.md
spec-theming-system.md
spec-tmux-interactive-input.md
spec-version-manager.md
spec-warp-adapter.md
spec-worktree-plugin-review-chatgpt-codex.md
spec-worktree-plugin-review-claude-opus.md
spec-worktree-plugin-review-gemini.md
spec-worktree-plugin.md
stallion.txt
td-48ecf2-workspace-agent-activity-status.md
td-8acb2c-git-plugin-performance.md
td-d2466a-dev-install-homebrew-integration.md
td-gradient-border-spec.md
tty-package-inline-editing.md
worktree-git-parity.md
worktree-lifecycle-hardening.md
research/
active/
herdr-session-persistence.md
lessons-from-herdr.md
hold/
replacing-tmux-with-herdr.md
screenshots/
sidecar-conversations.html
sidecar-conversations.png
sidecar-file-browser.png
sidecar-files.html
sidecar-files.png
sidecar-git.html
sidecar-git.png
sidecar-riders-din99d.txt
sidecar-riders.png
sidecar-td.html
sidecar-td.png
sidecar-td2.png
GEMINI.md
go.mod
go.sum
internal/
adapter/
adapter.go
amp/
adapter_test.go
adapter.go
doc.go
register.go
search.go
types.go
watcher.go
antigravity/
adapter_test.go
adapter.go
doc.go
register.go
search_test.go
search.go
types.go
watcher.go
cache/
cache_test.go
cache.go
doc.go
jsonl_test.go
jsonl.go
claudecode/
adapter_bench_test.go
adapter_test.go
adapter.go
doc.go
parser_test.go
register.go
search_test.go
search.go
stats.go
testdata/
empty.jsonl
malformed.jsonl
thinking_content.jsonl
tool_linking_edge_cases.jsonl
tool_linking.jsonl
valid_session_with_slug.jsonl
valid_session.jsonl
types.go
watcher.go
codex/
adapter_bench_test.go
adapter_test.go
adapter.go
current_test.go
doc.go
messages_test.go
register.go
search_test.go
search.go
sessiondb.go
types.go
watcher.go
copilot/
adapter_test.go
adapter.go
doc.go
register.go
search_test.go
search.go
testdata/
empty.jsonl
malformed.jsonl
tool_linking.jsonl
valid_events.jsonl
workspace.yaml
types.go
watcher.go
cursor/
adapter_test.go
adapter.go
doc.go
register.go
search_test.go
search.go
types.go
watcher.go
xml_test.go
detect.go
doc.go
kiro/
adapter.go
doc.go
kiro_test.go
register.go
search.go
types.go
watcher.go
omp/
doc.go
register.go
opencode/
adapter_test.go
adapter.go
doc.go
integration_test.go
register.go
search_test.go
search.go
testdata/
message/
ses_test_main/
msg_assistant_001.json
msg_user_001.json
part/
msg_assistant_001/
prt_text_001.json
prt_tool_001.json
msg_user_001/
prt_text_001.json
project/
global.json
test_project.json
session/
test_project/
ses_subagent.json
ses_test_main.json
types.go
watcher.go
pi/
adapter_test.go
adapter.go
doc.go
register.go
stats.go
testdata/
basic-session.jsonl
cron-session.jsonl
empty-session.jsonl
other-project-session.jsonl
telegram-session.jsonl
tool-session.jsonl
whatsapp-session.jsonl
types.go
watcher.go
piagent/
adapter_test.go
adapter.go
doc.go
register.go
stats.go
testdata/
session1.jsonl
session2.jsonl
watcher.go
pricing/
pricing_test.go
pricing.go
search_utils_test.go
search_utils.go
search.go
sqlitedsn_test.go
sqlitedsn.go
testutil/
doc.go
fixtures.go
tieredwatcher/
doc.go
tieredwatcher_test.go
tieredwatcher.go
warp/
adapter.go
doc.go
register.go
search_test.go
search.go
types.go
warp_test.go
watcher.go
agentactivity/
activity_test.go
activity.go
amp.go
antigravity.go
claude.go
codex.go
copilot.go
cursor.go
grok.go
opencode.go
pi.go
testdata/
amp/
evidence.md
false_positive.txt
proof.txt
title_compatibility.txt
... 710 moreFAQ
sidecar is a Claude Code plugin with 17 hand-picked skills for development work, indexed on Flowy. Install it with the command on its page. It includes create-adapter, create-modal, create-plugin. Its skills do not fire on their own yet. Request auto-invocation to have Flowy route them as you prompt. Free and open source.
- What is sidecar?
- You might never open your editor again. Status: Ready for daily use. Please report any issues you encounter.
- How do I install sidecar?
- Run these in Claude Code: npx -y skills add marcus/sidecar --agent claude-code. Then prompt normally.
- Does sidecar auto-invoke its skills?
- Not yet. It is indexed on Flowy as a plain plugin. Request auto-invocation on its page and Flowy will route its skills for you as you prompt.
- Is sidecar free?
- Yes. Flowy is free and open source, with nothing gated. You can read every skill in full before you install.