Skip to content

README.md

Latest commit

 

History

History
183 lines (138 loc) · 7.19 KB

README.md

File metadata and controls

183 lines (138 loc) · 7.19 KB
Raw

GCode

Build codecov License: Apache 2.0 PyPI version Stars

A local, interactive AI coding CLI. Chat with a free LLM (via OpenRouter) that can read/write/edit files, run shell commands (with your approval), search your codebase, and work with git.

GCode demo

Contributing

GCode is community-built, and contributions of every kind are welcome — bug reports, docs, tests, and features.

Install

pip install -e .

On Windows? See the Windows setup and troubleshooting guide for native, WSL2, and Git Bash instructions and known limitations.

Setup

GCode reads your API key from ~/.gcode/.env (not a project-root .env). Create it from the template and add your OpenRouter API key:

mkdir -p ~/.gcode
cp .env.example ~/.gcode/.env

Then edit ~/.gcode/.env:

OPENROUTER_API_KEY=sk-or-...

Get one at https://openrouter.ai/keys. (OPENAI_API_KEY is also accepted as a fallback.)

Configuration file

GCode reads optional settings from a .gcoderc file (in the project root, or ~/.gcode/.gcoderc for user-wide defaults). The format is simple key = value lines with # comments. Command-line flags and environment variables still take precedence over the file.

# .gcoderc
model = nvidia/nemotron-3-super-120b-a12b:free
auto_approve = false
bash_timeout = 300
system_prompt = You are GCode, a coding agent.

Supported keys:

Key Type Default Description
model string first free model Default model id (overridden by --model / GCODE_MODEL)
auto_approve bool false Skip bash confirmation (overridden by --yes)
bash_timeout int 300 Seconds before a bash command is killed
system_prompt string built-in Custom system prompt for new sessions

Skills

A skill is a Markdown file with extra instructions for GCode to follow — a house style, a domain checklist, project-specific conventions. Drop one into .gcode/skills/<name>.md (project-local) or ~/.gcode/skills/<name>.md (user-wide, available in every project); a project skill overrides a user skill of the same name.

GCode also reads Claude Code skills natively: ~/.claude/skills/ is scanned as an additional (lowest-precedence) source, accepting both its <name>/SKILL.md folder layout — with the YAML frontmatter description: used for /skills listings — and plain .md files. Precedence: project > user > claude, so a same-named local skill always wins.

# .gcode/skills/commit-style.md
# Commit style
Write commit messages as a single imperative sentence, no period, under 72 chars.
  • /skills — list every skill visible from the current directory, one per line (name, color-coded source tag, truncated description)
  • /skill <name> — activate one for the rest of the session (its content is appended to the session's system prompt)
  • /skill import <npm-package> — run npx <npm-package> in a scratch directory and copy any .md files it writes into the project's .gcode/skills/, same y/n approval as bash commands (see Safety below)

Use

gcode                            # start a session in the current directory
gcode --session work             # named, resumable session
gcode --model nvidia/nemotron-3-super-120b-a12b:free
gcode --yes                      # auto-approve bash (unsafe — know what you run)

Commands (start a line with /):

  • /help — show commands
  • /version — show the installed GCode version
  • /models — list every free model on OpenRouter
  • /model <id|#n> — switch models (use an id, or #n from /models)
  • /history — show recent turns
  • /status — quick git status
  • /skills — list skills (project, user, and ~/.claude/skills)
  • /skill <name> — activate a skill for this session
  • /skill import <npm-package> — import a skill via npx (asks for approval first)
  • /clear — start a fresh session
  • /quit — exit

Chat history persists across runs in ~/.gcode/.

Demo GIF

docs/demo.gif is recorded from a real session with vhs:

brew install vhs          # or: go install github.com/charmbracelet/vhs@latest
vhs demo/demo.tape        # writes docs/demo.gif

Notes for editing demo/demo.tape:

  • Set TypingSpeed needs explicit units — 155ms, not 155 (vhs parses a bare number as 155s = 155 seconds per keystroke).
  • Typed /commands work normally (the interactive slash menu only opens for a bare /), but the recording still launches with --model <id> because /models//model hit the live OpenRouter catalog at runtime, which is slow and nondeterministic to script.
  • Use --yes so execute_bash runs without the y/n gate (no keystroke timing to sync), and pick a tool-capable free model that responds reliably.
  • The recording runs in real time, so give each turn generous Sleep windows — free models are slow and rate-limited.

GCode streams the assistant's replies token-by-token, renders Markdown, and shows each tool call as ⏺ Tool(args) with a y/n gate before bash runs (skip the gate with --yes).

Models

The default nvidia/nemotron-3-super-120b-a12b:free supports tool use. Not every free model does — some (e.g. meta-llama/llama-3.2-3b-instruct:free) return a 404 "No endpoints found that support tool use". Stick to tool-capable models, or any model you pass via /model / --model / GCODE_MODEL. Free models are also heavily rate-limited on OpenRouter's shared tier; if you get a 429, wait a moment and retry, or use your own OpenRouter key for higher limits.

Safety

Bash commands require a y/n confirmation by default. Only use --yes if you trust the agent and your prompts — it will run whatever the model requests. /skill import <package> runs an arbitrary npm package via npx and carries the same confirmation (and is skipped by the same --yes) — only import skills from packages you trust.

Contributors

Thanks to everyone who has contributed to GCode, whether through code, documentation, bug reports, testing, or other contributions. ❤️

Your contributions help make GCode better for everyone.

Contributions are always welcome! See CONTRIBUTING.md to get started.