coding-agent

coding-agent adds an editable Codex-based engineering agent to an existing repository. It uses Flue for orchestration, authenticates through the local Codex CLI, and keeps prompts, skills, model selection, and sandbox configuration in the project.

What you can do

• give the agent a one-off software-engineering task from the terminal;
• keep a reusable default prompt and add project-specific workflows;
• edit the bundled engineering skills locally;
• choose what the agent can access through Local, Docker, or Cloudflare provider configuration;
• integrate provider lifecycle operations with a stable CLI contract;
• use structured output, recovery records, and guarded cleanup in automation.

Quick start

Requirements: Node.js 22.19 or newer, Git, and an authenticated Codex CLI installation.

codex login
npx @design4pro/coding-agent init
npm install
npm run coding-agent -- --prompt=default

With one prompt file, running without an argument selects it automatically. With multiple files it opens an interactive list:

npm run coding-agent

# Run the complete staged workflow (or choose interactively when several exist)
npm run coding-agent -- --prompt=default --workflow=default

The initializer creates a .coding-agent/ workspace, adds coding-agent, tsx, and TypeScript to the host project's development dependencies, and adds npm scripts for direct runs, workflows, prompt enhancement, configuration audit, and workspace type-checking. It also installs agent guidance in AGENTS.md and docs/agents/. Existing content outside the managed Agent skills section is preserved. An existing .coding-agent/ directory is never overwritten.

For a guided installation, including initialization in another directory and provider selection, see Getting started.

Everyday commands

# Run one task
npm run coding-agent -- --prompt=checkout-fix

# Run the editable default prompt
npm run coding-agent

# Run the included full workflow
npm run coding-agent:workflow

# Audit the project's coding-agent configuration without modifying files
npm run coding-agent:audit

# Type-check the editable workspace
npm run coding-agent:check

See Daily work for task-writing tips, choosing a workflow, reviewing results, and handling interrupted runs.

Configuration at a glance

The files you normally edit are:

.coding-agent/
├── main.mts               # default workflow entry point
├── config.mts             # shared model selection
├── prompts/default.md     # named task prompt
├── skills/                # editable engineering skills
├── sandboxes/             # filesystem and environment access
├── workflow.mts           # interactive staged-workflow runner
└── workflows/             # full workflow and autonomous skill repair loops

The default Local sandbox works in the host project directory and does not provide OS isolation. Only add environment variables that the model genuinely needs. See Customizing the agent and Sandbox providers before changing access or using Docker or Cloudflare.

Documentation

• Documentation index — choose the right guide.
• Getting started — install, initialize, authenticate, and run the first task.
• Daily work — the normal edit, run, inspect, and iterate loop.
• Customizing the agent — prompts, workflows, skills, models, and sandbox access.
• CLI reference — commands, options, JSON output, and exit codes.
• Sandbox providers — Local, Docker, and Cloudflare prerequisites and boundaries.
• Operations and recovery — lifecycle integration, reconciliation, and safe cleanup.
• Migration — adopt newer APIs and roll back safely.

Contributor and release documentation is linked separately from the documentation index.

Package API

Applications that need a custom TypeScript workflow can compose the same primitives directly:

import { codex, loadSkills, run } from '@design4pro/coding-agent';
import { local } from '@design4pro/coding-agent/sandboxes/local';

const reply = await run({
  agent: codex({
    sandbox: local({ cwd: process.cwd() }),
    skills: loadSkills(new URL('./.coding-agent/skills/', import.meta.url)),
  }),
  prompt: 'Review the current change and report correctness issues.',
});

console.log(reply.text);

run() accepts exactly one of prompt or promptFile. codex() also allows replacing the model, sandbox, skills, and base instructions. The initializer is available as initProject().

Development

npm install
npm run check:types
npm test
npm run build

Release gates and publishing steps are documented in CI gates and Release process.

License

MIT