@gajae-code/coding-agent

中文文档
0.21.0发布于 2026/11/16MITTypeScriptES Module构建来源已验证近 30 天下载 7479

Gajae Code CLI with read, bash, edit, write tools and session management

原始使用文档
文档目录6 节
  1. External lifecycle notifications
  2. Windows psmux authority boundary
  3. Memory backends
  4. Hindsight quickstart
  5. Red-claw TUI theme
  6. Welcome banner fonts on Windows Terminal

@gajae-code/coding-agent

Core implementation package for the gjc coding agent in the gajae-code monorepo.

For installation, setup, provider configuration, model roles, slash commands, and full CLI reference, see:

Package-specific references:

External lifecycle notifications

GJC already exposes public lifecycle events through the extension/hook event contract. External notification integrations for Discord, Hermes, clawhip, or similar channels should be opt-in and subscribe to these events instead of scraping transcripts or logs:

  • turn_end — a model/tool turn finished. The public payload is { type: "turn_end", turnIndex, message, toolResults }.
  • agent_end — the agent loop for a submitted prompt reached a terminal boundary. The public payload is { type: "agent_end", messages }.

For simple local side effects that do not need a full extension, set the user-level completion.notifyCommand. GJC runs it on completed agent turns with GJC_NOTIFICATION_* environment variables (GJC_NOTIFICATION_TITLE, GJC_NOTIFICATION_BODY, GJC_NOTIFICATION_JSON, etc.); project settings cannot activate this command hook.

gjc config set completion.notifyCommand 'cmux notify --title "$GJC_NOTIFICATION_TITLE" --body "$GJC_NOTIFICATION_BODY"'

On macOS, GJC emits the terminal BEL for completion, approval, and ask notifications by default when notifications.terminalBell has not been configured. Set it to false to keep macOS terminals silent.

When GJC runs inside a cmux terminal (CMUX_WORKSPACE_ID is set), GJC best-effort renames that cmux workspace to the current GJC session name (with a GJC: prefix) — but only when the workspace still has its default title, so a name you pinned (or one set by a peer session sharing the workspace) is never overwritten. Opt out with GJC_NO_CMUX_RENAME=1.

Windows Terminal may keep BEL ([Console]::Write([char]7)) silent depending on profile and system sound settings even when notifications.terminalBell is enabled. For an audible Windows completion beep, configure a user-level PowerShell command hook instead:

gjc config set completion.notifyCommand 'powershell.exe -NoProfile -Command "[Console]::Beep(880, 300)"'

cmux notify returning successfully means GJC handed the completion event to cmux. cmux may still suppress the native desktop banner when the app/window is focused, the emitting workspace is active, or the notification panel is open. In those cases, check cmux's notification panel or unread workspace state instead of treating the missing banner as a GJC delivery failure. Recommended external mapping:

NotificationPublic eventStatus guidance
Turn finishedturn_endUse the handler's own sanitized status such as "finished".
Agent stopped/finishedagent_endTreat as terminal for the prompt.
Waiting/blocked/failedagent_end plus a caller-supplied safe summaryCurrent lifecycle events do not expose a separate structured waiting/blocked reason; inspect only public-safe, integration-owned state.

Forward only a minimal, caller-sanitized payload. Do not include raw prompts, assistant transcripts, hidden prompts, tool outputs, raw logs, host paths, private config, webhook URLs, channel IDs, tokens, or secrets. A safe notification payload should be built by the extension/hook itself, for example:

import type { ExtensionAPI } from "@gajae-code/coding-agent";

type PublicLifecycleNotification = {
    type: "turn_end" | "agent_end";
    status: "finished" | "stopped" | "failed" | "blocked" | "waiting";
    turnIndex?: number;
    timestamp: string;
    summary: string;
};

export default function lifecycleNotifier(pi: ExtensionAPI) {
    const enabled = process.env.GJC_LIFECYCLE_NOTIFY === "1";
    if (!enabled) return;

    const send = async (payload: PublicLifecycleNotification) => {
        // POST to Discord/Hermes/clawhip here. Keep target URLs and channel IDs in
        // private config or environment variables; never include them in payloads.
    };

    pi.on("turn_end", event =>
        send({
            type: "turn_end",
            status: "finished",
            turnIndex: event.turnIndex,
            timestamp: new Date().toISOString(),
            summary: "GJC turn finished",
        }),
    );

    pi.on("agent_end", () =>
        send({
            type: "agent_end",
            status: "stopped",
            timestamp: new Date().toISOString(),
            summary: "GJC prompt reached a terminal lifecycle boundary",
        }),
    );
}

This is the supported repo-native lifecycle notification path. It is not Claude Code hook compatibility, and it remains disabled unless the user configures an extension/hook handler and private delivery target.

Windows psmux authority boundary

On native Windows, GJC-managed psmux sessions persist a per-owner ProviderAuthority: the exact resolved executable identity and an isolated tmux-compatible -L namespace. GJC_TMUX_COMMAND is an executable path/name only, never psmux -L …. Recover managed sessions through GJC so it reuses and re-proves that authority; do not fall back to ambient tmux/psmux or manually recreate a namespace. An unavailable, changed, or ambiguous authority fails closed.

Memory backends

The agent supports three mutually-exclusive memory backends, selected via the memory.backend setting (Settings → Memory tab, or ~/.gjc/agent/config.yml):

  • off (default) — no memory subsystem runs.
  • local — existing rollout-summarisation pipeline; writes memory_summary.md and consolidated artifacts under the agent dir.
  • hindsight — talks to a Hindsight server (Cloud or self-hosted Docker). Hindsight uses private backend lifecycle hooks to retain transcripts and recall context; compatibility-only internals remain for legacy backend calls, but GJC does not expose public coding-harness memory tools such as retain, recall, or reflect.

Hindsight quickstart

  1. Run a Hindsight server (Cloud or docker run -p 8888:8888 ghcr.io/vectorize-io/hindsight:latest).
  2. Set memory.backend = "hindsight" and hindsight.apiUrl = "http://localhost:8888" (or your Cloud URL).
  3. Optional environment overrides (env wins over settings):
    • HINDSIGHT_API_URL, HINDSIGHT_API_TOKEN — connection
    • HINDSIGHT_BANK_ID, HINDSIGHT_DYNAMIC_BANK_ID, HINDSIGHT_AGENT_NAME — bank addressing
    • HINDSIGHT_AUTO_RECALL, HINDSIGHT_AUTO_RETAIN, HINDSIGHT_RETAIN_MODE — lifecycle
    • HINDSIGHT_RECALL_BUDGET, HINDSIGHT_RECALL_MAX_TOKENS — recall sizing
    • HINDSIGHT_BANK_MISSION, HINDSIGHT_DEBUG

Switching backends mid-session is honoured on the next system-prompt rebuild and the next /memory slash command. Existing users with memories.enabled = true|false are migrated to memory.backend = "local"|"off" exactly once on first launch.

Red-claw TUI theme

The interactive TUI defaults to the bundled red-claw crustacean theme for dark terminals and the bundled blue-crab theme for light-appearance terminals, with matching welcome/icon assets. 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; set theme.dark: red-claw and theme.light: blue-crab in ~/.gjc/agent/config.yml to pin them.

Welcome banner fonts on Windows Terminal

The startup logo defaults to rounded Unicode box drawing. Windows Terminal can render it correctly when the selected profile font has the needed box-drawing glyphs; recommended choices are Cascadia Mono or Cascadia Mono Nerd Font. In Windows Terminal Settings, set the profile font face to one of those fonts, or add it to the profile JSON:

"font": {
  "face": "Cascadia Mono"
}

For terminals or fonts with broken rounded corners, set startup.welcomeBannerMode in ~/.gjc/agent/config.yml to one of unicode, square, or ascii. square keeps a Unicode-looking logo using square corners (┌ ┐ └ ┘) while ascii uses only +, -, and |.

版本与发布记录

@gajae-code/coding-agent 共发布 157 个版本,首次发布于 2026/05/28;过去 12 个月发布了 157 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.21.0latest2026/11/16今天
0.20.1-nightly.20261108030927.43711868338.gb4127889c4a8nightly2026/11/15今天
0.20.1-nightly.20261108030927.43590872198.gb4127889c4a82026/11/141 天前
0.20.1-nightly.20261108030927.43424588966.gb4127889c4a82026/11/132 天前
0.20.1-nightly.20261108030927.43222623203.gb4127889c4a82026/11/123 天前
0.20.1-nightly.20261108030927.43016219422.gb4127889c4a82026/11/114 天前

关于 @gajae-code/coding-agent 的常见问题

@gajae-code/coding-agent 是什么?

Gajae Code CLI with read, bash, edit, write tools and session management

如何安装 @gajae-code/coding-agent?

在项目目录运行 npm install @gajae-code/coding-agent,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 gjc,可以用 npx gjc 直接运行。

@gajae-code/coding-agent 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gajae-code/coding-agent 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@gajae-code/coding-agent 可以商用吗?

@gajae-code/coding-agent 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gajae-code/coding-agent 的下载量有多少?

根据 npm 官方下载统计,@gajae-code/coding-agent 在 2026/10/16 – 2026/11/14 这 30 天内被下载 7,479 次,日均约 249 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gajae-code/coding-agent 还在维护吗?

最新版本 0.21.0 发布于 2026/11/16(今天);至今共发布 157 个版本,其中过去 12 个月发布了 157 个;首次发布于 2026/05/28。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。