code-agent-kit

Runtime-agnostic toolkit for running coding agents through one shared interface and one CLI.

Scope

This package is intentionally narrow:

• One runtime contract for Claude, Codex, Gemini, and Copilot
• One CLI command for running prompts
• Optional system prompts
• Optional text file attachments
• Optional session resume and event streaming when the selected runtime supports them

Everything related to PR automation, GitHub Actions, git workspaces, and lease-based worktrees has been removed.

Installation

npm install @nimashoghi/code-agent-kit
npm install -g @nimashoghi/code-agent-kit

Install any runtime-specific dependencies and CLIs you plan to use:

# Claude runtime
npm install @anthropic-ai/claude-agent-sdk

# Gemini runtime expects the local `gemini` CLI on PATH
# Copilot runtime expects `github-copilot-cli` on PATH

CLI

code-agent-kit run --runtime claude "Fix the failing tests"
code-agent-kit run --model claude-sonnet-4-20250514 "Fix the failing tests"
code-agent-kit run --runtime codex --system "Run tests before finishing." "Add validation"
code-agent-kit run --runtime gemini --file src/runtime.ts "Summarize this file"
code-agent-kit run --runtime claude --resume session-123 "Continue the last task"
code-agent-kit status <run-id>
code-agent-kit kill <run-id>

run options:

• --runtime <name>: claude, codex, copilot, or gemini
• --model <name>: model override for the selected runtime
• --directory <path>: working directory for the agent
• --system <text>: system prompt text
• --file <path>: attach a text file, repeatable
• --resume <sessionId>: resume a previous session when supported
• --timeout <ms>: timeout in milliseconds

run prints a short unique run ID immediately, then executes the agent. The final output is always written to an output file for that run. status reports whether the run is still running or finished, how many seconds it has been running or ran for, and the output file path. Verbose agent logs are intentionally hidden by default and only written when CODE_AGENT_KIT_DEBUG_LOGS=1 is set for the run. kill sends SIGTERM to a running agent by run ID so the run is recorded as interrupted instead of remaining stuck in running.

When you explicitly pass --runtime, the CLI propagates that choice to child processes through CODE_AGENT_KIT_RUNTIME. Nested invocations of code-agent-kit run use that value as their default runtime.

Local Config

The CLI reads a local JSON config from the standard config directory:

• Linux: ${XDG_CONFIG_HOME:-~/.config}/code-agent-kit/config.json
• macOS: ~/Library/Application Support/code-agent-kit/config.json
• Windows: %APPDATA%\\code-agent-kit\\config.json

Supported keys:

• runtime
• model
• systemPrompt
• directory
• timeoutMs

Priority is:

1. Explicit CLI flags
2. Propagated CODE_AGENT_KIT_RUNTIME
3. DEFAULT_RUNTIME
4. Local config
5. Built-in defaults

Examples:

code-agent-kit config set runtime codex
code-agent-kit config set model gpt-5-codex
code-agent-kit config set timeoutMs 300000
code-agent-kit config show
code-agent-kit config unset model
code-agent-kit config path

Debug logging example:

CODE_AGENT_KIT_DEBUG_LOGS=1 code-agent-kit run "Fix the failing tests"
CODE_AGENT_KIT_DEBUG_LOGS=1 code-agent-kit status <run-id>

Library Usage

import { ClaudeRuntime } from "@nimashoghi/code-agent-kit/claude";

const runtime = new ClaudeRuntime({ model: "claude-sonnet-4-20250514" });

const result = await runtime.run({
  workingDirectory: "/my/project",
  prompt: "Fix the failing tests",
  systemPrompt: "Run tests before finishing.",
  attachments: [{ path: "src/runtime.ts" }],
});

console.log(result.output);

You can also create runtimes generically:

import { createRuntime } from "@nimashoghi/code-agent-kit";

const runtime = createRuntime({ name: "codex" });

Runtime Contract

interface RuntimeRunOptions {
  workingDirectory: string;
  prompt: string;
  systemPrompt?: string;
  attachments?: { path: string; content?: string }[];
  env?: Record<string, string>;
  session?: { mode: "new" } | { mode: "resume"; sessionId: string };
  timeoutMs?: number;
  signal?: AbortSignal;
  onEvent?: (event: RuntimeEvent) => void;
}

attachments are normalized into the user prompt so every runtime can consume the same shape.

Development

npm install
npx vitest run
npx tsc --noEmit
npx tsup