Getting Started

Prerequisites

• Bun installed and available as bun.
• A Git repository for the project you want gjc to work on.
• tmux if you want the recommended gjc --tmux experience.
• At least one reachable model provider.

For OS and shell notes, see Recommended Environment.

Install

Gajae-Code is published through the npm registry as gajae-code. Use Bun for the recommended runtime workflow:

bun install -g gajae-code

This installs the gjc binary. The scoped package is also available as @gajae-code/coding-agent.

Launch

Start the recommended tmux-backed experience:

gjc --tmux

Bare gjc launches directly without creating or attaching a tmux session:

gjc

Run inside an isolated Git worktree when you want a safer, branch-local workspace. --worktree takes an optional branch-like name and creates a GJC-managed sibling worktree; it is not a filesystem path:

gjc --tmux --worktree my-task-branch

If you already created a worktree directory, launch from that directory instead:

cd ../my-task-worktree && gjc --tmux

Authenticate a provider

Gajae-Code routes through model providers, so at least one must be reachable before you can pick a model.

API-key environment variables are the simplest path. Export the key for the provider you want and gjc resolves it automatically:

See Environment variables for the full list.

Register a custom provider with a preset, which writes a models.yml entry referencing a documented env var name (it does not store the secret):

gjc setup provider --preset minimax
gjc setup provider --preset minimax-cn
gjc setup provider --preset glm

The same presets are available inside the TUI:

/provider add --preset glm
/provider add zai

OAuth providers sign in through your browser instead of an env var. Anthropic, OpenAI Code, Google (Gemini CLI / Antigravity), and GitLab Duo each have a built-in browser callback port; the resulting OAuth credentials are stored locally in agent.db.

When gjc resolves a key for a provider, it uses this order:

1. CLI --api-key
2. Stored API key (agent.db)
3. Stored OAuth credential (agent.db)
4. Environment variable
5. models.yml apiKey

Then pick a model with /model in the TUI, or --model / --models on the CLI. For details, see Models and credentials.

Advanced: to move OAuth refresh tokens off your laptop onto a shared host, see gjc auth-broker in Models and credentials.

Pass an image

At startup, prefix a local path with @:

gjc @screenshot.png "What should I change?"

Inside the TUI, copy an image to the system clipboard and use Paste image from clipboard (Ctrl+V on Linux/macOS, Alt+V on Windows), or type #paste-image and choose the prompt action. If clipboard access is unavailable, paste or pass the image file path as @path/to/image.png.

Run the loop

Gajae-Code focuses on one useful loop:

deep-interview -> ralplan -> ultragoal
                         └─ optional team execution when parallel tmux workers help

• deep-interview — clarify intent, affected behavior, non-goals, and acceptance checks.
• ralplan — build and critique the plan before any mutation.
• ultragoal — carry the work through implementation, revision, verification, and an evidence summary.

Add team only when coordinated parallel tmux workers help. team requires running inside a tmux session ($TMUX set) — launch the gjc CLI from a shell first, e.g. gjc --tmux. A concrete bug-fix pass might look like:

/skill:deep-interview clarify the bug, affected behavior, non-goals, and acceptance checks
/skill:ralplan turn the clarified bug report into a reviewed fix plan
gjc ultragoal create-goals --brief-file <approved-plan>
# Optional only for parallel work:
gjc team 2:executor "split implementation and verification for this bug fix"
gjc ultragoal complete-goals

Try research mode

Use rlm when the job is exploratory research rather than direct code mutation:

gjc rlm

It opens a notebook-style research/REPL loop backed by a persistent Python kernel and a hard-gated toolset: python, read, web_search, search_tool_bm25, read-only bash, goal, and complete_research. The run writes notebook.ipynb, report.md, metadata, and agent-session artifacts under .gjc/_session-<gjcSessionId>/rlm/<rlmSessionId>/.