@coregit/agent

Universal AI agent runtime — CLI + SDK for tool-using LLM agents.

A self-contained agent loop that takes a user prompt, calls an LLM with tool definitions, executes tools (read/write/edit/exec/grep/glob/ls/web-search/fetch/image-gen/HITL/sub-agents/todos), and streams JSON-per-line events to stdout. Works as a CLI binary or as an importable SDK.

Install

npm install @coregit/agent

CLI

Bundled at dist/agent.js (registered as coregit-agent):

coregit-agent --prompt "fix the bug in app.ts" --model pro --work-dir ./my-project

Common flags:

| Flag | Default | Meaning | |---|---|---| | --prompt | required | User message | | --model | pro | auto | light | pro | deep | | --mode | normal | normal | plan | implement | | --work-dir | cwd | Project root | | --session-id | random | Resume across runs | | --skills-dir | ./skills | SKILL.md plugin directory | | --hitl-dir | /tmp/hitl | Human-in-the-loop request files | | --blocked-tools | "" | Comma-separated tool names to disable | | --max-iterations | 200 | Hard stop for the agent loop | | --image PATH | — | Attach an image to the user message (repeatable) | | --history-file PATH | — | Resume from prior message history (JSON) | | --restore-checkpoint PATH | — | Resume from a saved checkpoint |

Events are emitted one-per-line as JSON: session-start, text-delta, reasoning-delta, tool-call-start, tool-result, usage-update, session-end, etc. See src/types.ts (AgentEvent).

SDK

import { runAgent } from "@coregit/agent";

await runAgent({
  model: "pro",
  userMessage: "implement /health endpoint",
  sessionId: crypto.randomUUID(),
  workDir: process.cwd(),
  env: process.env as Record<string, string>,
  maxIterations: 100,
});

Types: AgentConfig, AgentEvent, Message, ToolCall, ToolContext, ToolDefinition, ToolExecutionResult, Middleware.

Environment

Required in proxy mode (production):

| Variable | Purpose | |---|---| | AGENT_API_URL | Base URL of the proxy that holds provider API keys (e.g. https://api.example.com) | | AGENT_SESSION_TOKEN | Bearer token for the proxy | | AGENT_USERNAME | Forwarded to the proxy via X-Agent-Project | | AGENT_PROJECT_SLUG | Same |

Optional:

| Variable | Purpose | |---|---| | AGENT_PROXY_FORMAT | openai (default) or anthropic — wire format the proxy speaks | | AGENT_TENANT | Storage tenant override | | AGENT_AUTH_TOKEN | Used with direct storage mode | | STORAGE_API_URL | Direct mode only — your storage backend | | ANTHROPIC_API_KEY | Direct mode only — for Anthropic models |

Local development (no proxy):

AGENT_LLM_DIRECT=1 \
  GOOGLE_GENERATIVE_AI_API_KEY=... \
  OPENROUTER_API_KEY=... \
  ANTHROPIC_API_KEY=... \
  coregit-agent --prompt "..." --model pro

Proxy formats

The runtime supports two wire formats for the upstream proxy. Pick one with AGENT_PROXY_FORMAT:

openai (default)

Agent sends POST ${AGENT_API_URL}/v1/chat/completions in OpenAI Chat Completions shape. Proxy is expected to authenticate the request, inject provider keys (selected via the X-Agent-Model header), and forward to the actual provider (OpenRouter, OpenAI, etc.). The proxy may translate to provider-native formats if needed.

anthropic

Agent sends POST ${AGENT_API_URL}/v1/messages in Anthropic Messages shape (with cache_control breakpoints, tool_use/tool_result blocks, adaptive thinking, etc.). Proxy authenticates the request and forwards as-is to api.anthropic.com/v1/messages with the real x-api-key. Use this when your proxy backs onto Anthropic only.

Both modes share the same agent-side env (AGENT_API_URL, AGENT_SESSION_TOKEN) and headers (X-Agent-Model, X-Agent-Session, X-Agent-OpenAI-Token). Only the request/response body shape differs.

Skills

Skills are markdown plugins (SKILL.md files) loaded from --skills-dir. Each subdirectory becomes a skill the agent can read on demand. Ship your own skill packs as separate npm packages.

Build

npm install
npm run build           # tsc → dist/*.{js,d.ts}  + esbuild bundle → dist/agent.js
npm run typecheck
npm test

License

MIT