Troubleshooting

This page covers the most common issues you’ll encounter and how to fix them.

Installation & Startup

”command not found: gee-code”

The CLI isn’t on your PATH.

# Check if the binary exists
ls -la ~/.local/bin/gee-code

# Add to your shell profile (~/.zshrc or ~/.bashrc)
export PATH="$HOME/.local/bin:$PATH"

# Reload your shell
source ~/.zshrc

If the binary doesn’t exist, reinstall:

curl -fsSL https://gee-desktop.s3.amazonaws.com/GeeCode/install.sh | bash

Python version errors

Gee-Code requires Python 3.10 or later.

# Check your version
python3 --version

# macOS: install via Homebrew
brew install python@3.12

# Linux: use your package manager
sudo apt install python3.12

If you have multiple Python versions, ensure python3 points to 3.10+.

Node.js missing

The MCP server layer requires Node.js 18+.

node --version

# macOS
brew install node

# Linux
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install nodejs

Authentication

”No API key found”

Gee-Code resolves API keys in this order:

Credentials store — scoped credentials (gee/team/endeavor)
Credentials file — ~/.gee-code/credentials.json
Environment variable — e.g., ANTHROPIC_API_KEY
Gee backend — via your authenticated session

To fix:

# Option 1: Set an environment variable
export ANTHROPIC_API_KEY=sk-ant-your-key-here

# Option 2: Authenticate to the Gee platform
gee-code auth login

# Option 3: Check what's configured
gee-code config show

“401 Unauthorized” or “Invalid credentials”

Your API key or session token is invalid or expired.

Provider API key: Verify it in the provider’s dashboard (Anthropic Console, OpenAI Platform, etc.)
Gee session: Re-authenticate with gee-code auth login
Check for typos: Look for trailing spaces or missing characters in your key
Key format: Anthropic keys start with sk-ant-, OpenAI keys start with sk-

Credentials file permissions

The credentials file should have restricted permissions:

chmod 600 ~/.gee-code/credentials.json

If the file is corrupted, delete it and re-authenticate:

rm ~/.gee-code/credentials.json
gee-code auth login

Models & Providers

”Model not found” or “Unknown model alias”

Use /models to see all available models and their aliases.

Common aliases:

Alias	Model
`claude` or `sonnet`	Claude Sonnet 4.5
`opus`	Claude Opus 4.6
`haiku`	Claude Haiku 4.5
`gpt-5`	GPT-5
`gpt-4o`	GPT-4o
`groq-llama`	Llama via Groq

Switch models with:

/model sonnet
/model opus

For custom or full model IDs, use the complete identifier (e.g., claude-opus-4-6).

Rate limits (HTTP 429)

You’ve hit the provider’s rate limit. Gee-Code retries automatically with exponential backoff (2s, 4s, 8s, up to 60s).

If you keep hitting limits:

Switch providers — /model gpt-5 or /model groq-llama
Wait — check the error message for the reset time
Reduce load — avoid rapid multi-turn loops on rate-limited providers
Check your plan — some providers have tier-based rate limits

Groq and Cerebras enforce minimum intervals between requests (2s and 1s respectively). This is handled automatically.

Provider overloaded (HTTP 503/529)

The AI provider is temporarily overloaded. Gee-Code retries automatically. If it persists, switch to a different provider with /model.

Tool Execution

File not found errors

Gee-Code uses absolute paths internally. If a file operation fails:

# Verify the file exists
ls -la /path/to/file

# Check your working directory
pwd

# Use /cwd to change the working directory
/cwd /path/to/project

Command timeouts

Bash commands timeout after 120 seconds by default. For long-running operations:

The AI can increase the timeout per-command (up to 600s)
Dev servers are automatically backgrounded
Use /status to check running background jobs
Use KillPort to stop a server on a specific port

”Command blocked: Overly broad search”

Gee-Code blocks filesystem searches that target excessively broad paths (like / or ~/) to prevent system hangs. Narrow your search:

# Instead of searching everything:
# find / -name "*.py"

# Target a specific directory:
# find ./src -name "*.py"

The Glob and Grep tools handle this automatically by skipping .git, node_modules, __pycache__, and other noise directories.

Context & Token Limits

”Token limit exceeded” or context too large

Gee-Code manages context automatically. When context approaches the limit (~180k tokens), it compacts older messages down to ~40k tokens. Tool outputs are the first to be trimmed.

If you’re hitting limits frequently:

Start a fresh conversation — /clear
Be selective with context — use /add for specific files rather than entire directories
Use named sessions — keep different tasks in separate sessions to avoid context bloat

Large file handling

Files over 100k characters are truncated when read into context. For large files:

Read specific line ranges: the AI can use offset and limit parameters
Search within files using Grep instead of reading the whole file
Break large operations into smaller, focused tasks

MCP Server

MCP server fails to start

The MCP server is the tool execution layer. If it fails:

# Check if the port is already in use
lsof -i :8090

# Kill the existing process
kill -9 <PID>

If dependencies are missing, reinstall:

pip install -r requirements.txt

Tools unavailable in MCP context

Some tools are excluded from MCP for safety:

Task / TaskOutput / TaskList / TaskCancel — prevents recursive agent spawning
AskUserQuestion — requires terminal interaction (uses file-based IPC in MCP mode)

If a tool isn’t available, use it directly in the terminal session instead.

Skills & Agents

”Skill not found”

# List available skills
/skills

# Check local skill directories
ls -la .gee/skills/
ls -la ~/.gee-code/skills/

If a skill exists locally but isn’t recognized, sync it:

# Validate first
/validate .gee/skills/my-skill

# Then sync to server
# (use SyncSkill tool or gee-code sync-skill)

Skill creation limits (autonomous mode)

Autonomous agents have skill creation limits to prevent runaway behavior:

Limit	Default
Per activation	1
Per day	3
Total self-created	20
Max active	5
Max instruction tokens	2,000
Auto-disable after failures	3 consecutive

These can be adjusted in your configuration if needed.

Agent approval prompts

Certain actions require explicit approval, even in autonomous mode:

Destructive git operations (force push, hard reset)
Creating or deleting skills
Bead plan approval
File operations outside the working directory

Review the action in the approval prompt before accepting.

Memory & Continuity

Memory not persisting

Check that the memory system is enabled:

gee-code config show
# Look for: memory_enabled: true

Enable it if disabled:

gee-code config set memory_enabled true

Corrupted continuity ledger

If your session state seems wrong or the ledger file is corrupted:

# Back up the current ledger
cp .gee/continuity.md .gee/continuity.md.bak

# Delete and let it regenerate
rm .gee/continuity.md

The ledger will be recreated on the next session.

Sessions not resuming

Named sessions are stored per-project. To resume:

/resume

This shows recent sessions. If a session doesn’t appear:

Verify you’re in the correct project directory
Check that .gee/ exists in the project root
Sessions from other projects won’t appear

Configuration

Config file syntax errors

If Gee-Code fails to start with a JSON error:

# Validate the config file
python3 -m json.tool ~/.gee-code/config.json

# If corrupted, reset to defaults
rm ~/.gee-code/config.json

Gee-Code recreates config files with defaults when they’re missing.

Project not initialized

If project-specific features aren’t working:

# Initialize the project
/init

# This creates .gee/ with:
# - gee.md (project guidance)
# - config.json (project settings)
# - continuity.md (session state)

Getting More Help

If your issue isn’t covered here:

Check the logs — Gee-Code outputs diagnostic information to the terminal
Use /status — shows current state, running tasks, and potential issues
File an issue — github.com/mj12ep/gee-code/issues
Join the community — ask in the Gee community forums