gdmcode

Quick start

Five steps to get from zero to a working coding agent.

1. Install

pipx install gdmcode

Installs gdm into an isolated environment. pipx is recommended over pip install --user because it avoids dependency conflicts. Install pipx first if needed: pip install pipx.

2. Verify the version

gdm version

Prints the installed version and shows which API providers are configured. If no provider is shown, proceed to step 3.

3. Connect a model

Set an API key (pick one):

gdm login grok      # xAI Grok — recommended
gdm login gemini    # Google Gemini — free tier available
gdm login codex     # OpenAI Codex

Credentials are stored in the OS keychain. They are never written to disk in plain text.

If direct provider access is blocked in your country or network, use the relay flow from inside the interactive shell:

gdm
/proxy
/proxy token

Paste the relay token at the hidden prompt. Keep provider API keys local; the relay forwards requests and should not store provider keys server-side.

You can run gdm health after login/proxy setup to check API connectivity, the database, tool availability, and budget state.

To disconnect later, run gdm logout grok or use /logout grok inside the interactive shell. /logout all forgets stored provider and proxy credentials; environment variables or TOML keys must be removed manually if they are still present.

4. Navigate to your project

cd my-project

gdm reads the current directory as the project root. It discovers .gdm/config.toml (project config) and .gdm/instructions.md (project-specific agent instructions) automatically.

5. Run the agent

gdm "fix the login bug"

If you start gdm before connecting a model, it shows setup guidance and keeps slash commands available instead of loading the agent loop. Once connected, the agent will read relevant files, plan a solution, and propose edits. Type hey as a quick connection test; if the provider rejects the request, gdm explains whether it looks like no LLM, invalid key, rate limit, billing/credit, or network/proxy trouble. At autonomy level 2 (default) it will ask before writing files or running shell commands. Lower the level for more prompts; raise it for more independence.

Single-shot (non-interactive):

gdm code --prompt "add input validation to the register form" --yes

Next steps