Code Companion

A native GTK4/libadwaita desktop application for working with AI coding assistants like Claude Code. Provides a visual IDE-like environment with session history, file editing, terminal, Git integration, and project notes.

Screenshots

Beyond the IDE basics, Code Companion adds an MCP control surface for the embedded session, a tmux session supervisor (Claude survives IDE restarts), cross-machine sync, and a cross-project coordination hub (catalog + inter-project mailbox). The provider layer is a multi-adapter architecture — Claude Code today, room for Gemini/Codex CLIs next.

Features

Project Manager

Register and manage multiple projects
Single-click to select, double-click to open
Lock mechanism prevents opening the same project twice
Prompt Search — search across every past Claude prompt in all registered projects and jump to the source project
Session summaries — the last session's handoff summary (résumé + next-session plan) is shown on the card
Live agent observability badges (token spend, cost, context-window meter) — see below

Project Workspace

The embedded Claude session lives in a persistent bottom pane (survives IDE-window restarts — see Session supervisor); a header activity bar switches the sidebar between Files, Git, AI Sessions, Notes, Problems, Issues, and Messages.

Sidebar tabs:

Files Tab (F)

File Tree — Browse project files with Material Design icons and git status indicators
Unified Search — Search files by name and content, with find & replace
Tasks Panel — Run VSCode tasks from .vscode/tasks.json

Git Tab (G)

Changes Panel:
- View staged and unstaged changes
- Stage/unstage individual files or all at once
- Commit with message
- Push/Pull with HTTPS authentication dialog and credential storage
- Auto-refresh on file changes (centralized monitoring)
History Panel:
- Browse commit history with filtering (by message/author/hash)
- View commit details (files list + full message + per-file diff)
- Checkout, reset, revert commits
Branch Management:
- Create, switch, delete branches
- Branch popover with quick access

AI Sessions Tab (C)

Browse past AI CLI sessions (lazy loading for performance)
Filter by preview text or date
View messages with tool calls, thinking blocks, code/diff display
One-click AI CLI session launch
Provider selection in Settings (currently: Claude Code)

Notes Tab (N)

My Notes — Personal notes in notes/ folder with New Note button
Docs — Documentation from docs/ folder and CLAUDE.md
TODOs — Auto-extracted from code (TODO:, FIXME:, HACK:, XXX:, NOTE:)

Problems Tab (P)

Multi-language linters — a registry-driven Problems panel runs the right tool per file type: ruff + mypy (Python), yamllint (YAML), PyMarkdown (Markdown), ShellCheck (shell), ESLint (JS/TS). Toggle each in Settings → Linters; a linter runs only when the project has its file types and the tool is available.
Quick install — missing linters show an Install button: Python tools install into the project venv (uv add --dev); system tools (ShellCheck) run their install command in a terminal. ./install.sh linters bulk-installs the system ones.
Agent-callable — MCP list_linters / run_linter let the embedded session lint a file on demand and see the results land in the same panel.
File Grouping — Problems grouped by file with error counts
Code Preview — View problem location with syntax highlighting
Copy to Clipboard — Copy single problem or all problems

Issues Tab

Browse/filter GitHub issues (open/closed/all) for the project's repo
Create issues; open a detail view with body + comments (Markdown), close/reopen
Send to Claude — hand an issue to the embedded session as a prepared prompt
Auth via the git credential/keyring PAT (no separate login)

Messages Tab

Inter-project mailbox — send/receive messages between your projects without GitHub
Inbox/Sent/All filter; thread view with replies, status (open/in-progress/done/rejected)
Recipient picked from the project catalog; addressed by canonical git remote
Private and synced across machines alongside your other synced data

Main Area

File Editor — Syntax highlighting via GtkSourceView 5, autosave on focus loss, go-to-line
Script Toolbar — polyglot Run button with arguments dialog (Python, shell, Node.js, Deno/TS, Go, Ruby — shown when the tool is installed), code outline for .py/.md files
Markdown Preview — WebKit-based preview with syntax highlighting (highlight.js)
Terminal Tabs — Embedded VTE terminal with Dracula theme, left padding, and auto environment activation (Python venv, direnv, mise; toggle via terminal.auto_activate_env)
Session View — Claude session content with Markdown support
Commit Detail View — Files list + commit message + unified diff
Image Viewer & SVG Editor — Zoomable image viewer and an SVG editor; binary files get a read-only info view

Claude Query Editor

Query Editor — a persistent Markdown prompt editor for the embedded session, with GtkSourceView highlighting and optional spell check (libspelling, per-language picker via editor.spellcheck_language)
Snippets — quick-access text snippets live in the Query Editor header (first few inline, the rest in a … overflow; right-click to delete)

Settings & Preferences

Theme: System/Light/Dark via libadwaita
Syntax Scheme: All GtkSourceView schemes available
Font: Family, size, line height (shared by editor + terminal)
Editor: Tab size, insert spaces, word wrap
File Tree: Show/hide hidden files
Linters: Enable/disable ruff and mypy, ignore specific codes
Window State: Auto-saves size, position, sidebar width, maximized state

AI Session Integration

MCP control surface — each project window runs a local Model Context Protocol server (bearer-token, 127.0.0.1) so the embedded Claude session can act on this window: read the workspace state and selection, open files, show diffs/commits, read problems, run linters, create and run tasks (.vscode/tasks.json), add notes, and create GitHub issues. Toggle with the mcp.enabled preference. Full tool catalogue: docs/mcp.md.
Cross-project tools — from any session, list_projects / resolve_project discover sibling projects and send_message / list_messages / reply_message / resolve_message drive the inter-project mailbox.
Session supervisor — the Claude session runs inside a per-project tmux session, so closing and reopening the IDE window (or restarting Code Companion) re-attaches instead of killing claude. The MCP port is stable and reserved across the restart. The Project Manager shows a live dot per project (green = running, amber = needs attention) and can kill or reconcile orphan sessions. Requires tmux; without it the session simply ends on window close.
Notifications — Claude Notification hooks surface as desktop notifications and an amber card indicator in the Project Manager.

Multi-Project & Sync

Git-centric Project Manager — per-project status badges (dirty ●, ahead ↑N, behind ↓N, PR/issue counts, pending-messages ✉N), a smart "Updated " label, rename, and a New Project button (git init → register → open).
Cross-machine sync — opt-in, git-backed 3-way merge of Claude session history, memory, plans, session summaries, and the message store to a private remote you control. Keyed by each project's canonical git identity, so data follows a project across machines. Selected-projects or backup (registry-wide) modes.
Secure credentials — git/GitHub tokens are stored in the desktop keyring (libsecret) when available, with a graceful fallback to git's credential helper.

Git Worktrees & Multi-Agent Orchestration

Worktree cards — spin off a git worktree from a project card's menu ("New Worktree…"); worktree cards nest and indent under their parent project with a branch glyph, and each opens in its own window.
Merge back — a "Merge back…" action previews the merge first (no working-tree touch), then merges or flags conflicts.
Completion reports — an agent working in a worktree signals it is done (MCP report_worktree_complete); the parent card shows a ⑂ N ready badge, and you can review/resolve the report.
MCP orchestration — create_worktree / list_worktrees / preview_merge / merge_worktree / report_worktree_complete / list_worktree_reports let a session drive the whole fan-out/merge flow.
Discovery — worktrees created with a plain git worktree add in a terminal are picked up automatically.

Agent Observability

Live token badge — projects with a running session show a ⚡ badge with the estimated cost and output tokens; the tooltip breaks down input / output / cache-write / cache-read and the $ estimate.
Context-window meter — a ◔ N% ctx pill shows how full the active session's context window is right now, shifting green → amber → red as it fills.
Per-session usage — the AI Sessions history lists per-session token counts and estimated cost, plus project-wide and "today" totals.

GUI Test Harness (optional)

The assistant can launch, drive (click/type by accessibility role+name, coordinate clicks and key presses via the wlroots virtual-input protocols), and screenshot another project's GTK/Qt GUI in an isolated headless Wayland compositor — like Playwright, but for native desktop apps. Requires cage/grim/wlr-randr/wtype (see INSTALL.md).

Installation

Quick install (recommended)

The install script is the easiest path — it detects your package manager (dnf/apt/pacman), installs the system and Python dependencies, and wires up the launcher, icon, and app-menu entry for you:

git clone https://github.com/typedev/code-companion.git
cd code-companion
./install.sh

Then run code-companion from a terminal or launch it from your app menu. Later, ./install.sh update pulls and re-syncs, and ./install.sh uninstall removes it. See INSTALL.md for the full walkthrough (update/uninstall, config paths, troubleshooting).

Prefer to install by hand — or install.sh doesn't recognise your distro? Follow the manual steps below; they install exactly what the script does.

Requirements (manual setup)

System dependencies (Fedora):

sudo dnf install cairo-devel cairo-gobject-devel gobject-introspection-devel \
    gtk4-devel libadwaita-devel gtksourceview5-devel vte291-gtk4-devel \
    webkitgtk6.0-devel libgit2-devel libspelling-devel \
    python3-devel meson ninja-build ripgrep fd-find

The cairo-*/gobject-introspection-devel/meson packages are needed so uv sync can build the PyGObject/pycairo bindings against your system libraries.

System dependencies (Ubuntu/Debian):

sudo apt install libgtk-4-dev libadwaita-1-dev libgtksourceview-5-dev \
    libvte-2.91-gtk4-dev libwebkitgtk-6.0-dev libgit2-dev \
    libspelling-1-dev gir1.2-spelling-1 \
    libcairo2-dev libgirepository-2.0-dev pkg-config python3-dev \
    meson ninja-build ripgrep fd-find

Package names above are for current Ubuntu (25.10 / 26.04 LTS "Resolute"). The libgirepository-2.0-dev package (girepository 2.0) is required by PyGObject ≥ 3.52.

Optional — native GUI test harness (cage, grim, wlr-randr, wtype): lets the assistant launch, drive and screenshot another project's GTK/Qt GUI in an isolated headless Wayland compositor. Not required to run the app. Install via sudo dnf install cage grim wlr-randr wtype (Fedora) / sudo apt install cage grim wlr-randr wtype (Ubuntu/Debian, from repos not Snap) / sudo pacman -S cage grim wlr-randr wtype (Arch). The semantic tree/click layer also uses the AT-SPI stack (at-spi2-core + the Atspi binding), which ships with GTK4. See INSTALL.md.

Python Setup

# Clone the repository
git clone https://github.com/typedev/code-companion.git
cd code-companion

# Install Python dependencies with uv
uv sync

# Run the application
uv run python -m src.main

Optional runtime tools

These are not required to launch the app, but improve specific features. The install.sh script installs ripgrep/fd for you; the rest are on demand.

Tool / package	Feature	Without it
`ripgrep` (`rg`)	Unified search (content)	Falls back to `grep` — slower, less `.gitignore`-aware
`fd` / `fd-find`	Unified search (file names)	Falls back to `find` — slower
`hunspell-<lang>` dictionaries	Spell check in Query Editor	Language missing from the picker (no crash)
`tmux` (≥ 3.2)	Keeps the Claude session alive across window restarts	Session ends when the project window closes
`uv`	App launch (`bin/code-companion` runs `uv run` on every start)	App won't start

On Debian/Ubuntu the fd binary is installed as fdfind — the app detects both names automatically, no symlink needed.

Platform notes

Console warnings: launching from a terminal prints PyGIWarning and Gtk.StyleContext ... deprecated messages (GTK 4.10+). These are cosmetic and do not affect functionality.
Markdown preview: code highlighting (highlight.js) is bundled locally and works offline. If the preview renders blank, it's usually the WebKitGTK sandbox — install bubblewrap and xdg-dbus-proxy.
Launching from the app menu: the launcher calls uv run, so uv must be on the PATH of your desktop session. If it lives in ~/.local/bin, make sure that directory is on the session PATH (log out/in after adding it).
Git HTTPS auth: push/pull credentials are saved via git's credential store in ~/.git-credentials (plain text), the same as on other distros.

Usage

Open Project Manager

uv run python -m src.main

Open a specific project directly

uv run python -m src.main --project /path/to/your/project

Architecture

src/
├── main.py                  # Entry point, NON_UNIQUE application
├── project_manager.py       # Project selection window
├── project_window.py        # Main workspace window
├── models/                  # Data models
│   ├── project.py           # Project model
│   ├── session.py           # Session model
│   ├── message.py           # Message model
│   └── tool_call.py         # Tool call model
├── widgets/                 # UI components
│   ├── file_tree.py         # File browser with git status, gitignore filtering
│   ├── file_editor.py       # Code editor with autosave, go-to-line
│   ├── unified_search.py    # Unified search (files + content) with replace
│   ├── terminal_view.py     # VTE terminal with Dracula theme
│   ├── session_view.py      # Claude session content viewer
│   ├── claude_history_panel.py   # Claude sessions list with filtering
│   ├── code_view.py         # Read-only code display + DiffView
│   ├── git_changes_panel.py # Git changes (stage/commit/push/pull)
│   ├── git_history_panel.py # Git commit history with filtering
│   ├── commit_detail_view.py# Commit details (files + message + diff)
│   ├── branch_popover.py    # Branch management popover
│   ├── tasks_panel.py       # VSCode tasks.json runner
│   ├── notes_panel.py       # Notes panel (My Notes + Docs + TODOs)
│   ├── problems_panel.py    # Problems sidebar (ruff/mypy)
│   ├── problems_detail_view.py  # Problems detail with code preview
│   ├── script_toolbar.py    # Run button + Outline for scripts
│   ├── markdown_preview.py  # WebKit markdown preview
│   ├── query_editor.py      # Persistent Claude prompt editor (spellcheck + snippets header)
│   ├── snippets_bar.py      # Quick-access snippets (rendered in the Query Editor header)
│   ├── prompt_search_window.py  # Cross-project search over past Claude prompts
│   ├── image_viewer.py / svg_editor.py / binary_file_view.py  # Non-text file views
│   ├── preferences_dialog.py# Settings dialog
│   └── ...
├── services/                # Business logic
│   ├── history_adapter.py / adapter_registry.py / adapters/  # Multi-provider AI-CLI adapters
│   ├── history.py           # Claude session reader (low-level JSONL)
│   ├── project_registry.py / project_lock.py    # Projects storage + FlockLock locks
│   ├── project_status_service.py    # PM card status badges + cache
│   ├── git_service.py / credential_service.py   # Git ops + keyring credentials
│   ├── issues_service.py    # GitHub Issues (REST via urllib)
│   ├── tasks_service.py / toast_service.py / settings_service.py / snippets_service.py
│   ├── rules_service.py     # CLAUDE.md rules management
│   ├── file_monitor_service.py / problems_service.py / async_runner.py
│   ├── icon_cache.py / python_outline.py / markdown_outline.py
│   ├── mcp_server.py        # Per-window MCP control surface (FastMCP)
│   ├── gui_harness.py / gui_agent.py    # Headless GUI test harness
│   ├── session_summary_service.py / session_notify.py   # Handoff summaries + notifications
│   ├── session_insight_service.py / model_pricing.py    # Token usage/context + cost estimate
│   ├── prompt_search.py     # Cross-project prompt index/search
│   ├── worktree_reports.py  # Worktree completion reports (multi-agent orchestration)
│   ├── project_catalog.py / message_store.py    # Coordination hub (catalog + mailbox)
│   └── sync_*.py            # Cross-machine sync (service/engine/repo/recovery/lock/state)
├── utils/                   # paths, project_identity, claude_session (tmux), git_auth, …
└── resources/
    └── icons/               # Material Design SVG icons

Key Design Decisions

Multi-process architecture — Each project opens in a separate process (Gio.ApplicationFlags.NON_UNIQUE)
Lock files — /tmp/code-companion-locks/ prevents duplicate project instances
Project registry — ~/.config/code-companion/projects.json stores registered projects
Settings — ~/.config/code-companion/settings.json stores user preferences
AI Provider abstraction — HistoryAdapter interface for multi-provider support
Material Design Icons — Pre-loaded SVG icons from vscode-material-icon-theme with O(1) lookup
Centralized file monitoring — FileMonitorService handles all file watching with debouncing
Lazy loading — AI history and problems load only when needed (background thread)
Git authentication — HTTPS credentials dialog with git credential storage

Roadmap

Third-Party Credits

Icons: Material Icon Theme (MIT License)
Markdown: mistune (BSD-3 License)
Syntax Highlighting: highlight.js (BSD-3 License)

License

Apache License 2.0

Author

Alexander Lubovenko (@typedev)

Name		Name	Last commit message	Last commit date
Latest commit History 166 Commits
.vscode		.vscode
bin		bin
data		data
docs		docs
images		images
src		src
tests		tests
tools/gui-harness-spike		tools/gui-harness-spike
.gitignore		.gitignore
.python-version		.python-version
CLAUDE.md		CLAUDE.md
INSTALL.md		INSTALL.md
README.md		README.md
claude-companion-spec.md		claude-companion-spec.md
install.sh		install.sh
main.py		main.py
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

Code Companion

Screenshots

Features

Project Manager

Project Workspace

Files Tab (F)

Git Tab (G)

AI Sessions Tab (C)

Notes Tab (N)

Problems Tab (P)

Issues Tab

Messages Tab

Main Area

Claude Query Editor

Settings & Preferences

AI Session Integration

Multi-Project & Sync

Git Worktrees & Multi-Agent Orchestration

Agent Observability

GUI Test Harness (optional)

Installation

Quick install (recommended)

Requirements (manual setup)

Python Setup

Optional runtime tools

Platform notes

Usage

Open Project Manager

Open a specific project directly

Architecture

Key Design Decisions

Roadmap

Third-Party Credits

License

Author

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages