guyide is the AI-friendly CLI bridge for GuyIDE: a single static Go binary that lets agents and humans drive nvim, tmux, and the Debug Adapter Protocol (DAP) through stable, scriptable commands.

Status: alpha (v0.0.0-dev) on branch feature/cli-skill-bridge. Not yet released to brew or go install. See Phasing below.

AI agents driving an IDE need a stable, narrow contract — not raw msgpack-RPC, not shell-escaped vimscript, not screen-scraped tmux output. guyide turns the GuyIDE stack into verbs:

guyide doctor                # is everything wired up?
guyide env --json            # what socket / session / pane am I in?
guyide debug start           # launch a dap session
guyide debug state --json    # where am I stopped, what are the locals?
guyide tmux watch --until '... build complete' --timeout 30s

Humans running the same commands in a tmux pane get a styled, Crush-themed report. Agents piping into --json get stable ndjson tagged "schema": "guyide/v1".

guyide auto-detects whether to render for humans or machines. Precedence:

1. --json flag → ndjson machine output
2. --no-color flag → plain text, no ANSI, no emoji
3. NO_COLOR=1 env → plain text
4. CI=true env → plain text
5. Stdout is not a TTY (piped / redirected) → JSON
6. Otherwise → full Crush palette (Charmtone via lipgloss)

This means a skill calling guyide debug state from a subshell automatically gets parseable JSON; a human running the same thing in their tmux pane sees panels and badges.

If you have Go 1.23+ installed:

# Latest released tag
go install github.com/guysoft/guyide-cli/cmd/guyide@latest

# Or follow the main branch (gets unreleased features)
go install github.com/guysoft/guyide-cli/cmd/guyide@main

The binary lands in $(go env GOBIN) (or $(go env GOPATH)/bin). Make sure that directory is on your PATH.

Branch names with slashes (e.g. feature/installer) are rejected by the Go module proxy. Use the commit SHA instead:

go install github.com/guysoft/guyide-cli/cmd/guyide@<commit-sha>

Once v0.1.0+ ships, Homebrew + tarball downloads will be available. macOS and Windows users may need to bypass Gatekeeper / SmartScreen on first run; signed releases are planned for Phase 2.

git clone -b feature/cli-skill-bridge https://github.com/guysoft/guyide-cli
cd guyide-cli
go build -o ~/.local/bin/guyide ./cmd/guyide
guyide version

Each command supports --json, --no-color, --socket, --session, --timeout, -v/--verbose.

Every nvim exec and nvim eval response includes the resolved socket, current buffer (full path), and cwd of the targeted nvim instance. This lets AI agents immediately detect when they are talking to the wrong nvim (e.g. a background headless instance) without having to run guyide env separately.

Example JSON response from guyide nvim exec "echo 1" --json:

{
  "schema": "guyide/v1",
  "level": "success",
  "command": "echo 1",
  "ok": true,
  "socket": "/tmp/nvim-ide-0-2.sock",
  "buffer": "/home/user/project/main.py",
  "cwd": "/home/user/project"
}

When agents or skills need to send commands to a specific tmux pane (e.g. "run ./run.sh in the terminal"), they historically had to hardcode absolute pane addresses like 0:1.1. This breaks whenever windows are reordered, sessions are restored, or the user manually splits panes.

guyide tmux send and guyide tmux watch now accept spatial role aliases that resolve to the correct pane in the caller's current window based on actual pane geometry (pane_left, pane_top):

# Send a command to the terminal pane (bottom-left) in the current window
guyide tmux send terminal "./run.sh" Enter

# Watch the terminal pane for output
guyide tmux watch --pane terminal --until "ready|panic" --timeout 300s

# Still works: explicit targets for cross-window use
guyide tmux send 0:3.1 "make build" Enter

The resolution is purely geometric — it works regardless of how panes were created (tmux-ide layout, manual leader-% splits, or session restore). If the target is not a known role name, it passes through as a literal tmux target.

Phase 1 (this branch, target v0.1.0):

• Repo scaffold + output layer + discovery
• All commands listed above, including tmux watch --until
• Skill v2 rewrite for debug-reach (consumes this CLI exclusively)
• CI matrix (linux, macos, windows × go 1.23) + goreleaser

Phase 2 (target v0.2.0):

• GUYIDE_PANE_ROLE env injection by tmux-ide (complements spatial resolution)
• guyide debug eval, debug list-configs, guyide events ndjson stream
• cosign-signed releases, SLSA provenance
• NvGuy lazy hook to auto-install the skill
• Optional guyide mcp subcommand

GPL-3.0 — matches the rest of the GuyIDE family.