GuyIDE

A modular terminal IDE where your AI agent can control the debugger, your sessions survive restarts, and everything runs in the terminal.

+---------------------------+--------------+
| | |
| nvim (editor/debugger) | AI agent |
| | |
| | |
|---------------------------| |
| terminal | |
| (build/run output) | |
+---------------------------+--------------+

One keybinding. Full IDE. Close your laptop, reopen — everything is exactly where you left off.

Why GuyIDE?

Your AI can debug for you. Tell it "find why process_data() returns None" and it will set breakpoints, run the debugger, inspect variables, and report back what's wrong. No other terminal setup can do this.

Sessions survive anything. Editor state, AI conversation, terminal working directory — all restored automatically after a crash or reboot. Like Cursor's session restore, but in the terminal.

The AI sees what you see. It shares your tmux session — it can read build output, test failures, and server logs from the terminal pane and react to them.

Everything is swappable. Don't like neovim? Use Emacs. Prefer Claude Code over OpenCode? One config line. The workflow is the product.

Quick Start

Works on Linux and macOS (Intel + Apple Silicon). Windows users: run inside WSL.

One command

curl -fsSL https://github.com/guysoft/guyide-cli/releases/latest/download/guyide-$(uname -s | tr '[:upper:]''[:lower:]')-$(uname -m) \
-o ~/.local/bin/guyide && chmod +x ~/.local/bin/guyide
guyide install

Dev channel (latest `main` of every component)

Want the bleeding edge? Run on the dev channel — main HEAD of NvGuy, vscodium.nvim, tmux-ide and friends, with no compat gating.

curl -fsSL https://github.com/guysoft/guyide-cli/releases/latest/download/guyide-$(uname -s | tr '[:upper:]''[:lower:]')-$(uname -m) \
-o ~/.local/bin/guyide && chmod +x ~/.local/bin/guyide
guyide install --channel dev

You can flip an existing install at any time with guyide channel set dev (or back with guyide channel set stable), then guyide update to pull the new refs.

That's it. The installer:

Backs up any existing ~/.tmux.conf, ~/.config/nvim, and related state under ~/.guyide/backups/<timestamp>/ (kept forever).
Lays down NvGuy, the canonical ~/.tmux.conf, and your AI agent (OpenCode by default) under ~/.guyide/.
Symlinks ~/.config/nvim → ~/.guyide/components/nvim and ~/.local/bin/guyide → ~/.guyide/bin/guyide.
Runs guyide doctor to confirm the install is healthy.
Asks: "Start GuyIDE now? [Y/n]" — answer yes and it drops you straight into nvim with a WELCOME.md cheatsheet that explains how to enter IDE mode, save sessions, and reach the menu.

What you'll see on first launch

The welcome cheatsheet teaches you the five keys you actually need:

Keys	What it does
`Ctrl-a e`	Enter IDE mode (3-pane layout)
`Ctrl-a d`	Detach from tmux (your session keeps running)
`Ctrl-a Ctrl-r`	Restore the last saved session
`Ctrl-a ?`	Show the full list of tmux commands
`Space m`	Open the neovim menu bar (when the nvim pane is focused)

Day two

guyide doctor # health check
guyide update # pull latest stable refs (gated by compat matrix)
guyide channel set dev # opt into bleeding edge
guyide uninstall # restore from the most recent backup

Channels:stable tracks the last validated (NvGuy, vscodium.nvim, ...) triple baked into the guyide binary. dev tracks main HEAD on every component with no compat gating.

Custom prefix or driver? Edit ~/.guyide/config.yaml and re-run guyide install — the installer is idempotent.

Pick your own agent

The right-hand IDE pane is driven by an agent slot. GuyIDE ships with two supported agents — OpenCode (default) and Anthropic's Claude Code — and you can flip between them in one command:

guyide agent switch claude-code # switch to Claude Code
guyide agent switch opencode # switch back
guyide agent show # which agent is active right now?

That single command coordinates the four places agent state lives:

~/.guyide/config.yaml — the declared driver
~/.guyide/manifest.json — the install record
~/.guyide/components/tmux/guyide.conf — the canonical tmux options (@ide-agent, resurrect plugin, @resurrect-processes)
~/.tmux.conf — the mirror of (3) that tmux actually reads

Before any change, agent switch snapshots all four into ~/.guyide/backups/<timestamp>.tar.gz and records it in the manifest. The running tmux server is reloaded via source-file — no need to detach. To roll back, either run agent switch <previous-driver> again or extract the tarball:

tar -xzf ~/.guyide/backups/<timestamp>.tar.gz -C / \
&& tmux source-file ~/.tmux.conf

Run a wrapper script (pinned model / flags)

If your agent invocation has fixed flags (e.g. claude --model opus --dangerously-skip-permissions), wrap them in a script and point agent switch at it:

# ~/scripts/cld#!/usr/bin/env bashexec claude --model opus --dangerously-skip-permissions "$@"

guyide agent switch claude-code --command "~/scripts/cld"

Or via repeated --extra-arg (no wrapper needed):

guyide agent switch claude-code \
--command claude --extra-arg --model --extra-arg opus

Settings persist in ~/.guyide/config.yaml under the claude-code: block (cli, extra_args, resurrect_process, resurrect_plugin), so subsequent installs/upgrades preserve them.

Drift protection

agent switch refuses to proceed if ~/.tmux.conf has hand-edited lines outside the agent-owned block AND outside the canonical source. The error message points at the exact diff to inspect. If you've reviewed the foreign lines and want to keep them, re-run with --force. guyide doctor will report this as a warning so you don't lose work silently.

What's supported

Agent	Resurrect plugin	Process pattern	Status
`opencode` (default)	`guysoft/tmux-resurrect-opencode-sessions`	`~opencode`	supported since v0.2.0
`claude-code`	`guysoft/tmux-resurrect-claude-sessions`	`~claude`	supported since v0.3.0

Adding a new agent driver to upstream: see SUPPORT_MATRIX.md in guyide-cli.

Features

Breakthrough

Feature	What it does
AI-controlled debugging	The AI sets breakpoints, launches the debugger, inspects variable state, and reports findings — all programmatically via RPC
Full session continuity	Layout, editor session, AI conversation, and terminal state all survive restarts. Auto-saves every 15 minutes
AI terminal observability	The agent reads your terminal pane — it sees build errors, test output, and logs as they happen
Shared editor bridge	Any process in the tmux session can control neovim via the exposed RPC socket (`NVIM_IDE_SOCK`)

Standard

3-pane IDE layout with one keybinding (Ctrl-a e)
VSCode-compatible .vscode/launch.json for Run and Debug configurations
Full DAP debugger with UI panels (scopes, watches, stack frames, console)
Menu bar in neovim (F10 or <leader>m) — File, Edit, View, Git, Run, Tools, Window, and more
Session auto-save/restore per project directory
Vim-style pane navigation between tmux and nvim (h/j/k/l)
Mouse support enabled
Git integration — Neogit (magit-style UI), Gitsigns (inline blame, hunk ops), gitui (fast TUI via floating window), Telescope git pickers
LSP + completion via Mason, nvim-lspconfig, nvim-cmp
Treesitter syntax highlighting
Code minimap sidebar
File explorer (nvim-tree)
Fuzzy finder for files, buffers, symbols, diagnostics (Telescope)
Code formatting via conform.nvim
Tmux prefix: Ctrl-a (screen-style)

Key Bindings

tmux (prefix: `Ctrl-a`)

Binding	Action
`Ctrl-a e`	Create IDE layout
`Ctrl-a h/j/k/l`	Navigate panes
`Ctrl-a c`	New window
`Ctrl-a Ctrl-s`	Save session
`Ctrl-a Ctrl-r`	Restore session

Neovim

Binding	Action
`F10`	Menu bar
`F5`	Run
`F6`	Debug
`F9`	Toggle breakpoint
`F11` / `Shift-F11`	Step into / out
`Shift-F5`	Stop debugger

Architecture

Three independent, replaceable layers:

Layer	Default	Alternatives
Window Manager	tmux	zellij, screen
Editor	NvGuy (neovim)	Emacs, Helix, Vim
AI Agent	OpenCode	Claude Code, Aider, Goose

Swap the agent in one command (see Pick your own agent above):

guyide agent switch claude-code
guyide agent switch opencode

The full config that agent switch writes lives in ~/.guyide/config.yaml:

# ~/.guyide/config.yamlschema: guyide/config/v1channel: stablecomponents:
editor:
driver: nvimmultiplexer:
driver: tmuxagent:
driver: claude-code # flipped by `guyide agent switch`claude-code:
cli: claude # executable name (default)extra_args: ["--model", "opus"] # optional passthrough flagsresurrect_process: "~claude"# tmux-resurrect patternresurrect_plugin: "guysoft/tmux-resurrect-claude-sessions"

Editor and multiplexer swaps are not yet automated — for those, edit ~/.guyide/config.yaml directly and re-run guyide install.

Themes

GuyIDE ships with a default theme and an optional alternative. Pick one in ~/.tmux.conf.

Oasis (default)

set -g @plugin 'uhs-robert/tmux-oasis'set -g @oasis_flavor "lagoon"# also: night, midnight, abyss, starlight, desert,# sol, canyon, dune, cactus, mirage, twilight,# rose, dawn, dawnlight, day, dusk, dustset -g status-position top

Dracula (alternative)

set -g @plugin 'dracula/tmux'set -g @dracula-show-powerline trueset -g @dracula-show-left-icon session
set -g @dracula-plugins "cpu-usage"set -g status-position top

Components

tmux Layer

Plugin	Purpose
tmux-ide	3-pane IDE layout (`prefix + e`)
tmux-resurrect	Save/restore sessions
tmux-continuum	Auto-save every 15 min
tmux-resurrect-opencode-sessions	Preserve OpenCode conversations across restarts
tmux-resurrect-claude-sessions	Preserve Claude Code conversations across restarts
vim-tmux-navigator	Seamless pane navigation

Editor Layer — NvGuy

Neovim distribution (NvChad-based) with:

Menu bar via vim-quickui (13 menus)
vscodium.nvim — VSCode-like Run/Debug, reads launch.json
Full DAP debugger + UI panels
Session management (auto-save per directory)
Git UI (Neogit + Gitsigns + gitui.nvim for gitui TUI)

AI Agent Layer — OpenCode

Terminal AI coding agent that:

Lives in the right pane with full project access
Persists conversations across restarts
Controls the debugger via the debug-reach skill
Reads terminal output from other panes

Bundled OpenCode Skills

GuyIDE expects these skills installed under ~/.config/opencode/skills/:

Skill	Purpose	Source
`debug-reach`	Lets the AI control nvim's debugger via RPC	bundled in vscodium.nvim (`.opencode/skills/debug-reach`)

Verify after install:

ls ~/.config/opencode/skills/debug-reach/SKILL.md

AI Agent Layer — Claude Code

Terminal AI coding agent (by Anthropic) that:

Lives in the right pane with full project access
Persists conversations across restarts (via tmux-resurrect-claude-sessions)
Controls the debugger via the debug-reach skill
Reads terminal output from other panes

To use Claude Code instead of OpenCode, run:

guyide agent switch claude-code

See Pick your own agent for wrapper-script support, --extra-arg flags, drift protection, and rollback via snapshot.

Bundled Claude Code Skills

GuyIDE expects these skills installed under ~/.claude/skills/:

Skill	Purpose	Source
`debug-reach`	Lets the AI control nvim's debugger via RPC	bundled in vscodium.nvim (`.opencode/skills/debug-reach`)

Verify after install:

ls ~/.claude/skills/debug-reach/SKILL.md

AI Debugging Setup (debug-reach skill)

The debug-reach skill lets the AI agent control nvim's debugger. It ships with vscodium.nvim.

Install the skill

The skill lives inside vscodium.nvim. If you installed NvGuy, vscodium.nvim is already on disk under ~/.local/share/nvim/lazy/vscodium.nvim/ — just copy the skill from there:

For OpenCode:

mkdir -p ~/.config/opencode/skills
cp -r ~/.local/share/nvim/lazy/vscodium.nvim/.opencode/skills/debug-reach \
~/.config/opencode/skills/

For Claude Code:

mkdir -p ~/.claude/skills
cp -r ~/.local/share/nvim/lazy/vscodium.nvim/.opencode/skills/debug-reach \
~/.claude/skills/

If you don't run NvGuy, clone vscodium.nvim directly:

git clone https://github.com/guysoft/vscodium.nvim.git /tmp/vscodium-nvim
# OpenCode:
mkdir -p ~/.config/opencode/skills
cp -r /tmp/vscodium-nvim/.opencode/skills/debug-reach ~/.config/opencode/skills/
# Claude Code:
mkdir -p ~/.claude/skills
cp -r /tmp/vscodium-nvim/.opencode/skills/debug-reach ~/.claude/skills/

Verify:

# OpenCode:
ls ~/.config/opencode/skills/debug-reach/SKILL.md
# Claude Code:
ls ~/.claude/skills/debug-reach/SKILL.md

Use it

Just ask the AI to debug something:

"Debug why test_login fails — step through it"
"Set a breakpoint at main.py:42 and check what x is"
"Find what value user_id has when the error occurs"

The AI handles breakpoints, launches the session, inspects state, and reports back.

How it works (under the hood)

All three components collaborate:

Component	Role
tmux-ide	Exposes `NVIM_IDE_SOCK` (nvim's RPC socket) to the tmux session
vscodium.nvim	Provides `debug-rpc.lua` — the RPC API the agent calls
NvGuy	Wires up nvim-dap, dap-ui, mason-nvim-dap

Full Installation Details

Most users should not need this section — guyide install does everything below for you. Read on if you want to set up the stack manually, or to understand what the installer is actually doing.

Manual install (no guyide binary)

1. tmux + plugins

# --- 1a. Backup any existing tmux config ---
[ -f~/.tmux.conf ] && cp ~/.tmux.conf ~/.tmux.conf.bak.$(date +%Y%m%d-%H%M%S)# --- 1b. Install tpack (plugin manager) ---# macOS:
brew install tmuxpack/tpack/tpack
# Linux / anywhere with Go:# go install github.com/tmuxpack/tpack@latest# --- 1c. Drop in the canonical ~/.tmux.conf ---# See the "Complete tmux.conf reference" block below.# --- 1d. Install all declared plugins ---
tpack install # or: ~/go/bin/tpack install# Or, from inside a running tmux session: prefix + I# --- 1e. Wire up the IDE layout helper ---~/.tmux/plugins/tmux-ide/install.sh

2. NvGuy (neovim distribution)

BACKUP=~/.nvim-backup-$(date +%Y%m%d-%H%M%S)
mkdir -p "$BACKUP"
mv ~/.config/nvim "$BACKUP/nvim"2>/dev/null ||true
mv ~/.local/share/nvim "$BACKUP/nvim-data"2>/dev/null ||true
mv ~/.local/state/nvim "$BACKUP/nvim-state"2>/dev/null ||true
git clone https://github.com/guysoft/NvGuy.git ~/.config/nvim
nvim # plugins install automatically on first launch

3. OpenCode (AI agent)

curl -fsSL https://opencode.ai/install | bash
mkdir -p ~/.config/opencode/skills
cp -r ~/.local/share/nvim/lazy/vscodium.nvim/.opencode/skills/debug-reach \
~/.config/opencode/skills/

3-alt. Claude Code (AI agent — alternative)

npm install -g @anthropic-ai/claude-code
mkdir -p ~/.claude/skills
cp -r ~/.local/share/nvim/lazy/vscodium.nvim/.opencode/skills/debug-reach \
~/.claude/skills/
# Install the session-persistence plugin:
git clone https://github.com/guysoft/tmux-resurrect-claude-sessions \
~/.tmux/plugins/tmux-resurrect-claude-sessions
~/.tmux/plugins/tmux-resurrect-claude-sessions/install.sh

If you have the guyide binary installed, flip the agent slot with one command:

guyide agent switch claude-code

Otherwise, set the three agent-owned tmux options in ~/.tmux.conf by hand:

set -g @ide-agent "claude"set -g @plugin 'guysoft/tmux-resurrect-claude-sessions'set -g @resurrect-processes '~claude'

4. Launch

tmux
cd~/your-project
# Press Ctrl-a e — IDE layout appears

Complete tmux.conf reference

set -g prefix C-a
unbind C-b
bind C-a send-prefix
# Reload config with prefix-r
unbind r
bind r source-file ~/.tmux.conf
# vim-style mode keys + pane navigation
setw -g mode-keys vi
bind-key h select-pane -L
bind-key j select-pane -D
bind-key k select-pane -U
bind-key l select-pane -R
set -g mouse on
# Clipboard
bind-key -T copy-mode-vi y send-keys -X copy-selection-and-cancel
bind-key -T copy-mode-vi MouseDragEnd1Pane send-keys -X copy-selection-and-cancel
# Pane creation in current directorybind c new-window -c "#{pane_current_path}"bind'"' split-window -v -c "#{pane_current_path}"bind % split-window -h -c "#{pane_current_path}"# === Plugins ===set -g @plugin 'tmux-plugins/tmux-resurrect'set -g @plugin 'tmux-plugins/tmux-continuum'set -g @plugin 'christoomey/vim-tmux-navigator'set -g @plugin 'guysoft/tmux-resurrect-opencode-sessions'set -g @plugin 'guysoft/tmux-ide'# Session restore (continuum auto-saves every 15 min)set -g @continuum-restore 'on'set -g @resurrect-processes '~opencode'# === AI Agent: Claude Code (alternative) ===# Uncomment the block below and comment out the opencode lines above to switch# set -g @plugin 'guysoft/tmux-resurrect-claude-sessions'# set -g @ide-agent "claude-tmux"# set -g @resurrect-processes '~claude'# === Theme: Oasis (default) ===set -g @plugin 'uhs-robert/tmux-oasis'set -g @oasis_flavor "lagoon"set -g status-position top
# === Theme: Dracula (alternative) ===# Comment the Oasis block above and uncomment below to switch# set -g @plugin 'dracula/tmux'# set -g @dracula-show-powerline true# set -g @dracula-show-left-icon session# set -g @dracula-plugins "cpu-usage"# set -g status-position top# Initialize tpack (must stay at very bottom)
run '~/go/bin/tpack init'

Prerequisites

git, curl
tmux >= 2.0
Neovim >= 0.9
Node.js >= 18 (for OpenCode and/or Claude Code)
sqlite3 (for OpenCode session restoration)
tpack or TPM (plugin manager)

tpack PATH note:tpack installs to $GOPATH/bin (typically ~/go/bin). Either add that to your PATH, or use the absolute path in ~/.tmux.conf:
run '~/go/bin/tpack init'

Step-by-step with TPM instead of tpack

If you prefer TPM over tpack, replace run 'tpack init' with:

set -g @plugin 'tmux-plugins/tpm'
run '~/.tmux/plugins/tpm/tpm'

Then press prefix + I to install plugins.

Contributing

Each component has its own repo:

Component	Repo
tmux-ide	https://github.com/guysoft/tmux-ide
vscodium.nvim	https://github.com/guysoft/vscodium.nvim
NvGuy	https://github.com/guysoft/NvGuy
tmux-resurrect-opencode-sessions	https://github.com/guysoft/tmux-resurrect-opencode-sessions
tmux-resurrect-claude-sessions	https://github.com/guysoft/tmux-resurrect-claude-sessions

For GuyIDE meta-repo issues (documentation, integration, workflow): open an issue here.

License

GPL-3.0. See LICENSE for details.

Name		Name	Last commit message	Last commit date
Latest commit History 17 Commits
docs		docs
screenshots		screenshots
DEVELOPING.md		DEVELOPING.md
LICENSE		LICENSE
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation