Skip to content

guysoft/GuyIDE

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

16 Commits
docs
docs
 
 
screenshots
screenshots
 
 
DEVELOPING.md
DEVELOPING.md
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 

Repository files navigation

GuyIDE

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

AI paused at a breakpoint with full DAP UI — Locals, Stack, source marker, AI explaining the state

+---------------------------+--------------+
|                           |              |
|   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:

  1. Backs up any existing ~/.tmux.conf, ~/.config/nvim, and related state under ~/.guyide/backups/<timestamp>/ (kept forever).
  2. Lays down NvGuy, the canonical ~/.tmux.conf, and your AI agent (OpenCode by default) under ~/.guyide/.
  3. Symlinks ~/.config/nvim → ~/.guyide/components/nvim and ~/.local/bin/guyide → ~/.guyide/bin/guyide.
  4. Runs guyide doctor to confirm the install is healthy.
  5. 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.

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 in ~/.tmux.conf:

set -g @ide-agent "claude-tmux"  # swap AI agent (session-persistent)
set -g @ide-editor "emacs"       # swap editor

Or in ~/.guyide/config.yaml:

# ~/.guyide/config.yaml
schema: guyide/config/v1
channel: stable
components:
  editor:
    driver: nvim
  multiplexer:
    driver: tmux
  agent:
    driver: claude-code          # was: opencode (default)
claude-code:
  cli: claude                    # executable name (default)
  extra_args: ["--model", "opus"] # optional passthrough flags

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, dust
set -g status-position top

Dracula (alternative)

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

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, set in ~/.guyide/config.yaml:

agent: claude-code

Or directly in ~/.tmux.conf:

set -g @ide-agent "claude-tmux"

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

Then set in ~/.tmux.conf:

set -g @ide-agent "claude-tmux"

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 directory
bind 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.

About

TUI IDE setup. Put the I back in IDE.

Resources

Readme

License

GPL-3.0 license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors