Gajae-Code

Encode intention. Decode software.
A focused coding-agent runner for interviews, reviewed plans, tmux-native execution, and durable verification.

Gajae-Code is an experimental, beta-stage project. Expect rough edges and verify outputs before relying on it for important work.

Recent highlights

Mobile answers for coding agents — Gajae-Code now ships a configure-once notifications SDK and managed Telegram reference daemon. Each session exposes a loopback WebSocket discovery file and a generic action_needed/reply protocol so Telegram, Discord, Slack, mobile apps, or local tools can surface pending asks and route answers back without terminal scraping.

The bundled Telegram flow adds a threaded per-session surface with context updates, live/finalized output, image attachments, inline buttons, free-text replies, typing indicators, and double-check acknowledgements. gjc daemon keeps one safe long-poll owner per bot token so new sessions attach cleanly instead of tripping Telegram 409 conflicts.

Research and desktop-control highlights

rlm — an opt-in research/REPL mode. A Jupyter-notebook-style research session over the agent loop, backed by the shared persistent Python kernel with a hard-gated python + read + web_search toolset. Runs aggregate into .gjc/rlm/<session>/notebook.ipynb and synthesize a report.md on exit. Start it with gjc rlm.

computer-use — an experimental, opt-in desktop-control tool surface. Backed by native screenshot/input bindings and gated through settings/tool registration, it lets the agent see the screen and drive mouse/keyboard for local desktop coordination.

Website

Visit gajae-code.com for the Gajae Code landing page, quick-start guide, architecture overview, harness notes, bridge/RPC docs, skills, receipts, remote-control design, and troubleshooting.

What is Gajae-Code?

Gajae-Code (gjc) is an external coding-agent harness. It runs from the repository or worktree you choose, then gives the agent a small, explicit workflow surface:

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

It is intentionally not a hidden plugin for Codex CLI, Claude Code, OpenCode, or Claw Code. Start gjc beside those tools when you want structured planning, persistent evidence, tmux-backed workers, or an isolated worktree.

Install

bun install -g gajae-code

The scoped package is also available as @gajae-code/coding-agent.

Shell completion

GJC can generate a Fig/withfig-compatible spec for Microsoft inshellisense:

gjc completion inshellisense --install

The installer writes gjc.js plus a minimal index.js into inshellisense's default local spec directory (~/.fig/autocomplete/build). If that directory already has an unrelated index.js, GJC refuses to clobber it unless --force is explicit; use --dir <path> for a separate GJC-only spec directory.

Supported platforms

Prebuilt standalone release binaries are published only for:

• Linux — x64 and arm64
• Windows — x64
• macOS — Apple Silicon (arm64) and Intel (x64)

The npm/Bun package path and build-from-source also remain available on every platform.

macOS Intel install

Standalone release binaries are published for both Apple Silicon (gjc-darwin-arm64) and Intel (gjc-darwin-x64) macOS. You can also install through the npm/Bun package path or build from source:

bun install -g gajae-code
# or
curl -fsSL https://raw.githubusercontent.com/Yeachan-Heo/gajae-code/main/scripts/install.sh | sh -s -- --source

Windows (native install)

On a clean Windows 11 machine, install Bun first, then install gjc with Bun's global installer:

# 1. Install Bun
powershell -c "irm bun.sh/install.ps1|iex"

# 2. Restart the terminal so PATH and the Bun runtime refresh, then confirm Bun
bun --version

# 3. Install and verify gjc
bun install -g gajae-code
gjc --version
gjc --smoke-test

bun install -g places the gjc launcher in %USERPROFILE%\.bun\bin. That directory must be on PATH for gjc to resolve as a command. Bun's installer adds it automatically, but the change only applies to terminals started after installation — restart PowerShell (or sign out/in) if gjc is "not recognized".

Troubleshooting:

• gjc reports an old Bun runtime. Re-run the Bun installer above, restart the terminal, and confirm bun --version matches what gjc --version expects. If an older Bun still wins, make sure %USERPROFILE%\.bun\bin is first on PATH and remove any stale Bun installs shadowing it.
• gjc.exe exists but gjc is "not recognized". The launcher is installed but not on PATH. Confirm %USERPROFILE%\.bun\bin is listed in echo $env:Path, then restart the terminal.
• gjc --tmux starts without a tmux-backed session. Native Windows needs a tmux-compatible executable on PATH. For GJC-managed session/team guarantees, use WSL with real tmux, or another provider that round-trips tmux user options such as @gjc-profile. Native psmux can provide tmux/pmux/psmux commands, but that path is not fully supported for GJC ownership tags and team guarantees yet; see docs/environment-variables.md#interactive---tmux-startup-and-scrollmouse-profile.

Quick start

# Run directly in the current checkout
gjc

# Use a tmux-backed leader session
gjc --tmux

# Use an isolated worktree for risky or reviewable work
# --worktree takes an optional branch-like name, 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

Image input

GJC accepts images in two ways:

• CLI startup: prefix a local image path with @, for example gjc @screenshot.png "What should I change?".
• Interactive TUI: copy an image to the system clipboard and use the configured Paste image from clipboard key (Ctrl+V on Linux/macOS, Alt+V on Windows), or type #paste-image and choose the prompt action. When the clipboard is unavailable, paste or pass the image file path with @path/to/image.png instead.

Type # in the interactive editor to open prompt actions. In a tmux-backed session, choose Scroll to previous user input (for example via #prev) to enter tmux copy-mode at the previous rendered user message.

Inside a GJC session, use the public workflow surface:

/skill:deep-interview clarify ambiguous requirements
/skill:ralplan build and critique the implementation plan
gjc ultragoal create-goals --brief-file <approved-plan>
gjc ultragoal complete-goals

Add gjc team ... only when coordinated tmux workers materially help.

Core capabilities

• Interview before guessing: deep-interview turns vague requests into concrete requirements.
• Plan before mutation: ralplan reviews the approach before code changes.
• Execute with evidence: ultragoal tracks goals, revisions, checks, and completion evidence.
• Parallelize when useful: team coordinates tmux-backed workers for larger tasks.
• Stay external and reviewable: run from a chosen repo or worktree without patching another agent runtime.

Workflow surface

Gajae-Code ships four default workflow skills:

And four bundled role agents:

No sprawling default skill zoo: GJC improves by making this small method better.

Skill migration and bundled skill inspection

When moving a workflow into GJC, inspect the bundled defaults before installing or overwriting anything:

gjc skills list
gjc skills read ralplan
gjc setup defaults --check

gjc setup defaults installs the four bundled GJC workflow skills into your user .gjc directory and preserves existing local files by default. If --check reports missing or different files, compare the embedded copy with gjc skills read <name> first; use gjc setup defaults --force only when you intentionally want to replace local default workflow skill files.

Works beside your existing agent or bot

For evaluating Aside as an opt-in search/context retrieval sidecar, see docs/aside-integration.md. For generic third-party bot setup and provider-independent smokes, see docs/bot-integration.md. For the readiness classification across RPC, ACP, and Bridge/HTTPS surfaces, see docs/external-control-readiness.md. For lower-level protocol details, see docs/rpc.md and docs/bridge.md.

Configuration

Provider retry budgets live in ~/.gjc/config.yml:

retry:
  requestMaxRetries: 4
  streamMaxRetries: 100
  maxRetries: 3
  maxDelayMs: 300000

requestMaxRetries applies before a stream is established. streamMaxRetries applies only to replay-safe transient stream failures. Invalid auth, unsupported models/providers, malformed requests, context overflow, user aborts, and permanent quota failures remain fail-fast.

Good to read together

• GJC multivendor setup guide — a community guide for role-based provider/profile selection across Anthropic, OpenAI/Codex, Google/Gemini, xAI/Grok, and opencode-go. Treat its presets as user-level configuration guidance rather than bundled defaults; verify model availability and provider auth in your own environment before adopting them.

TUI identity

The default dark TUI identity is the GJC red-claw theme, while light-appearance terminals default to the bundled blue-crab theme. Three additional bundled migration themes — claude-code, codex, and opencode — mirror the look of those tools for easy eye-migration and are selectable from Settings or /theme. Explicit user theme settings still win.

Bundled theme grid

Pick from Settings (Appearance -> Dark theme / Light theme) or /theme.

Development

Install dependencies, build native bindings, and set up local defaults:

bun install
bun run build:native
bun run install:defaults

The .node binary for @gajae-code/natives is gitignored and required before any CLI invocation (install:defaults, dev:link, tests).

Canonical: build and link the dev gjc

To make the global gjc command run this checkout's TypeScript source (hot to every edit, with skills/natives working), link it onto your PATH:

bun install
bun run dev:link

dev:link symlinks gjc → packages/coding-agent/src/cli.ts into ~/.local/bin (override with GJC_DEV_LINK_DIR), replaces that managed target, warns and fails if another gjc still shadows it earlier on PATH, and runs --smoke-test to confirm @gajae-code/natives loads. Use bun run install:dev for the full bootstrap (install + link + `setup