npm package: @nimashoghi/code-agent-kit
Description: Multi-runtime coding agent runtime toolkit
Latest version: 0.4.1

# 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

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

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

```bash
# 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

```bash
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:

```bash
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:

```bash
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

```ts
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:

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

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

## Runtime Contract

```ts
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

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