@backendkit-labs/agent-coding

A production-ready coding agent engine built on @backendkit-labs/agent-core. Bundles 10 specialized agents, filesystem tools, multi-provider support (DeepSeek, OpenAI, Anthropic, Ollama, Kimi, Grok), automatic stack detection, persistent memory, QA review, reflection, and an orchestration pipeline — all in a single createCodingEngine() call.

Status: stable — Maintained and production-ready. No new features during the pilot phase.

Table of contents

• Installation
• Quick start
• createCodingEngine
• createCodingEngineFromConfig
• Providers
• Built-in agents
• Built-in tools
• Skill packs
• Orchestration pipeline
• Reflection engine
• MCP server integration
• Multi-agent examples
• Config file

Installation

npm install @backendkit-labs/agent-coding

All provider adapters are bundled — no separate packages needed.

Quick start

import { createCodingEngine } from '@backendkit-labs/agent-coding';

const engine = createCodingEngine({
  providers:       { deepseek: { apiKey: process.env.DEEPSEEK_API_KEY! } },
  defaultProvider: 'deepseek',
});

await engine.run('List all TypeScript files in src/ and tell me which ones have no tests');

That single call gives you: 10 specialized agents, filesystem tools (read/write/edit/search), persistent project memory, skill loading, and stack auto-detection.

createCodingEngine

The primary factory. Returns a fully configured AgentEngine.

Options reference

interface CodingEngineOptions {
  // Required
  providers:       ProvidersConfig;
  defaultProvider: string;

  // Agents and engine
  defaultAgent?:          string;       // default: 'general'
  workingDir?:            string;       // default: process.cwd()
  maxIterations?:         number;       // default: 100
  maxParallelAgents?:     number;       // default: 6

  // I/O
  transport?:             Transport;    // default: StdoutTransport

  // App identity
  appName?:               string;       // default: 'bk-agent' — used for ~/.{appName}/

  // Persistence
  disablePersistence?:    boolean;      // skip ProjectStore (useful for testing)

  // MCP servers
  mcpServers?:            MCPServerConfig[];

  // Context sharing
  subAgentContextMessages?: number;    // messages visible to sub-agents (recommend 10-20)

  // Iteration control
  onToolApproval?:   (toolName, agentId, argsPreview) => Promise<ToolApprovalDecision>;
  onIterationLimit?: (stats: IterationStats) => Promise<boolean>;
  onStep?:           (stats: IterationStats) => Promise<boolean>;

  // Orchestration
  orchestration?:    boolean | OrchestrationOptions;
}

Minimal setup

const engine = createCodingEngine({
  providers:       { deepseek: { apiKey: 'sk-...' } },
  defaultProvider: 'deepseek',
});

Multiple providers

const engine = createCodingEngine({
  providers: {
    deepseek:  { apiKey: process.env.DEEPSEEK_API_KEY! },
    anthropic: { apiKey: process.env.ANTHROPIC_API_KEY!, model: 'claude-opus-4-8' },
    ollama:    { host: 'http://localhost:11434', model: 'llama3.2' },
  },
  defaultProvider: 'deepseek',
  // Each agent profile can specify a provider override
});

With full orchestration

const engine = createCodingEngine({
  providers:       { deepseek: { apiKey: '...' } },
  defaultProvider: 'deepseek',
  orchestration:   true,
  // Enables:
  //   intent detection → domain detection → risk scoring
  //   policy engine → agent routing → QA auto-review → reflection
});

With MCP servers

const engine = createCodingEngine({
  providers:       { openai: { apiKey: '...' } },
  defaultProvider: 'openai',
  mcpServers: [
    { name: 'github',   command: 'npx', args: ['-y', '@modelcontextprotocol/server-github'],  env: { GITHUB_TOKEN: '...' } },
    { name: 'postgres', command: 'npx', args: ['-y', '@modelcontextprotocol/server-postgres'], env: { DATABASE_URL: '...' } },
  ],
  subAgentContextMessages: 15,
});

With manual tool approval

const engine = createCodingEngine({
  providers:       { deepseek: { apiKey: '...' } },
  defaultProvider: 'deepseek',
  onToolApproval:  async (toolName, agentId, argsPreview) => {
    const write = ['write_file', 'edit_file', 'run_command'];
    if (!write.includes(toolName)) return 'approve';
    console.log(`\n⚠  [${agentId}] ${toolName}:\n${argsPreview}\n`);
    const a = await prompt('Approve? (y/n/all): ');
    if (a === 'y')   return 'approve';
    if (a === 'all') return 'approve_all';
    return 'reject';
  },
});

createCodingEngineFromConfig

Reads credentials from ~/.{appName}/config.json. No code changes needed to switch providers:

import { createCodingEngineFromConfig } from '@backendkit-labs/agent-coding';

const engine = createCodingEngineFromConfig();

// With overrides
const engine = createCodingEngineFromConfig({
  workingDir:    '/my-project',
  orchestration: true,
});

Providers

DeepSeek

providers: {
  deepseek: {
    apiKey:       process.env.DEEPSEEK_API_KEY!,
    model?:       'deepseek-chat',    // default
    maxTokens?:   8192,
    temperature?: 0.7,
  }
}

OpenAI

providers: {
  openai: {
    apiKey:   process.env.OPENAI_API_KEY!,
    model?:   'gpt-4o',
    baseUrl?: 'https://api.openai.com/v1',
  }
}

Anthropic (Claude)

providers: {
  anthropic: {
    apiKey: process.env.ANTHROPIC_API_KEY!,
    model?: 'claude-sonnet-4-6',    // default
  }
}

Ollama (local — no API key)

# Prerequisites
ollama serve
ollama pull llama3.2

providers: {
  ollama: {
    host?:  'http://localhost:11434',
    model?: 'llama3.2',
  }
}

OpenAI-compatible (Kimi, Grok, any endpoint)

providers: {
  kimi: { apiKey: process.env.KIMI_API_KEY!, model: 'moonshot-v1-8k' },
  grok: { apiKey: process.env.GROK_API_KEY!, model: 'grok-3' },
  // Any OpenAI-compatible endpoint
  vllm: { apiKey: 'local', baseUrl: 'http://localhost:8080/v1', model: 'my-model' },
}

Built-in agents

Ten specialist agents are bundled. Orchestration routes tasks automatically; you can also select explicitly.

Selecting an agent

await engine.run('Audit src/ for SQL injection risks', { agentId: 'security-reviewer' });

Adding custom agents

Create ~/.bk-agent/agents/my-agent.json:

{
  "id":           "my-agent",
  "name":         "My Custom Agent",
  "systemPrompt": "You are specialized in ...",
  "tools":        ["read_file", "run_command"],
  "provider":     "anthropic"
}

Loaded automatically — no code changes needed.

Project agents and skills need a trusted project

Agents in {project}/.bk-agent/agents/ and skills in {project}/.bk-agent/skills/ are the repository's content, not yours: a cloned repo could ship an agent that replaces the built-in orchestrator with its own prompt and tools. So they load only for a project you trusted. Your own agents and skills under ~/.bk-agent/ always load.

/trust              # is this project trusted, and what would its project layer load
/trust add          # trust it (records the real path in ~/.bk-agent/trusted-projects.json)
/trust remove       # stop trusting it
/trust list

• Trust is by exact path: trusting ~/code does not trust a repository cloned inside it.
• For a project that is not trusted, the engine emits a warning naming what was left out. Skills load right after /trust add; agents the next time the agent starts.
• BK_TRUST_PROJECT=1 trusts every path (CI, containers). A host that decides by itself can pass trustedProject: true | false to createCodingEngine.
• A missing or damaged trust file means nobody is trusted.

Built-in tools

All agents have access to these tools via CODING_TOOLS:

Skill packs

Built-in packs activate based on detected project stack:

Orchestration pipeline

When orchestration: true, an intelligent routing layer runs before each LLM call:

Input
  → Intent Detection (feature? bug? refactor? question?)
  → Domain Detection (backend? frontend? security? ops?)
  → Risk Scoring (reads only? writes files? runs commands?)
  → Policy Engine (enforce domain-level rules)
  → Agent Selection (best agent for detected domain + risk)
  → LLM Call
  → QA Review (auto-review code-heavy responses)

Custom orchestration

orchestration: {
  capabilityMatrix: {
    'my-specialist': {
      owns:       ['payments', 'billing'],
      skills:     ['typescript', 'stripe'],
      baseWeight: 0.95,
    },
  },
  customRules: [
    {
      if:   { domain: 'security' },
      then: { mustInclude: ['security-reviewer'] },
    },
  ],
  enableQA:   true,
  noQA:       false,
  onQAReview: (review) => logger.info('[QA]', review),
}

Reflection engine

Observes failures across runs, promotes recurring patterns into policy rules:

orchestration: {
  reflection: true,
  // After each sprint:
  // 1. Failures logged to FailureCatalog
  // 2. Patterns with ≥3 occurrences promoted to PolicyRules
  // 3. lecciones-aprendidas.md updated
}

MCP server integration

mcpServers: [
  {
    name:    'code-intelligence',
    command: 'bk-mcp',               // @backendkit-labs/mcp-server
    args:    [],
    env:     { BK_APP_NAME: 'bk-agent', BK_CWD: process.cwd() },
  },
  {
    name:    'github',
    command: 'npx',
    args:    ['-y', '@modelcontextprotocol/server-github'],
    env:     { GITHUB_TOKEN: process.env.GITHUB_TOKEN! },
  },
],
subAgentContextMessages: 20,

Multi-agent examples

Feature implementation

await engine.run(`
  Implement JWT authentication middleware for Express:
  - Validate Bearer token in Authorization header
  - Attach decoded user to req.user
  - Return 401 with clear error messages
  - Include unit tests with valid/expired/malformed token cases
`);
// architect plans → backend-agent implements → qa-engineer writes tests

Security audit

await engine.run(`
  Audit all routes in src/routes/ for:
  1. Missing auth middleware
  2. SQL injection vulnerabilities
  3. Exposed sensitive data
  Output a prioritized fix list.
`, { agentId: 'security-reviewer' });

Database migration

await engine.run(`
  Write a zero-downtime migration: add NOT NULL column 
  'last_login_at TIMESTAMP DEFAULT NOW()' to the users table (50M rows).
  Include rollback script and backfill strategy.
`, { agentId: 'database-agent' });

Full stack refactor

await engine.run(`
  Refactor auth from session cookies to JWT.
  Update both Express middleware and React login flow.
  Keep backward compatibility for 2 more sprints.
`);
// backend-agent + frontend-agent + security-reviewer

Config file

~/.bk-agent/config.json:

{
  "defaultProvider": "deepseek",
  "providers": {
    "deepseek": { "apiKey": "sk-xxxx", "model": "deepseek-chat" },
    "anthropic": { "apiKey": "sk-ant-xxxx", "model": "claude-sonnet-4-6" },
    "ollama":    { "host": "http://localhost:11434", "model": "llama3.2" }
  },
  "mcpServers": [
    {
      "name": "github",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_xxxx" }
    }
  ]
}