Recipe: Code Assistant

What this builds

A code assistant that can read and write files, run shell commands (git, build tools, tests), and execute code in a sandboxed environment. Suitable for CI/CD automation, code review, and iterative development tasks.

Skills loaded by this recipe

• shell-execution-sandbox — shell tool with allowlist and opt-in build commands
• reasoning-strategy-selection — plan-execute-reflect for multi-step coding tasks
• tool-creation — tool registration and allowedTools
• observability-instrumentation — verbose live output for development

Complete implementation

import { ReactiveAgents } from "@reactive-agents/runtime";
import { shellExecuteTool, shellExecuteHandler } from "@reactive-agents/tools";

// Configure the shell tool with build commands enabled
const shellTool = {
  definition: shellExecuteTool,
  handler: shellExecuteHandler({
    additionalCommands: ["bun", "node", "npm", "git"],
    timeoutMs: 60_000,       // 60s for build/test commands
    maxOutputChars: 8_000,   // increase for verbose test output
    cwd: process.cwd(),
  }),
};

const agent = await ReactiveAgents.create()
  .withName("code-assistant")
  .withProvider("anthropic")
  .withReasoning({
    defaultStrategy: "plan-execute-reflect",
    maxIterations: 30,
  })
  .withTools({
    tools: [shellTool],
    allowedTools: ["shell-execute", "file-read", "file-write", "checkpoint", "final-answer"],
  })
  .withObservability({ verbosity: "verbose", live: true })
  .withCostTracking({ perSession: 2.0, daily: 20.0 })
  .withSystemPrompt(`
    You are a code assistant with shell and file access.

    Workflow for coding tasks:
    1. Read relevant files with file-read before making changes.
    2. Checkpoint your plan before starting significant edits.
    3. Make targeted, focused changes — do not rewrite files unnecessarily.
    4. After writing files, run tests with shell-execute to verify.
    5. Use "git status" and "git diff" to review changes before finalizing.
    6. Report what you changed and whether tests passed.

    Allowed shell commands: git, ls, cat, grep, find, bun, node, npm, mkdir, cp, mv, touch, wc, head, tail, diff
    Blocked: rm, chmod, chown (use mv to "delete" files if needed)
  `)
  .build();

// Example: fix a bug
const result = await agent.run(`
  Fix the failing test in packages/auth/tests/login.test.ts.
  The test expects validateToken to return null for expired tokens,
  but the current implementation throws an error instead.
`);

console.log(result.output);
await agent.dispose();

Key variations

Read-only code review (no writes)

const reviewTool = {
  definition: shellExecuteTool,
  handler: shellExecuteHandler({
    allowedCommands: ["git", "ls", "cat", "grep", "find", "head", "tail", "wc", "diff"],
  }),
};

const reviewer = await ReactiveAgents.create()
  .withProvider("anthropic")
  .withTools({
    tools: [reviewTool],
    allowedTools: ["shell-execute", "file-read", "checkpoint"],
  })
  .withSystemPrompt("Review code for issues. Do not make any changes. Report findings only.")
  .build();

Docker-sandboxed code execution

const sandboxTool = {
  definition: shellExecuteTool,
  handler: shellExecuteHandler({
    additionalCommands: ["node", "python3"],
    dockerEscalation: { enabled: true },
    // Inline code (node --eval, python -c) runs in isolated Docker containers
  }),
};

Audit logging for production

import type { ShellAuditEntry } from "@reactive-agents/tools";

const auditedTool = {
  definition: shellExecuteTool,
  handler: shellExecuteHandler({
    additionalCommands: ["bun", "git"],
    onAudit: (entry: ShellAuditEntry) => {
      logger.info("shell-execute", {
        command: entry.command,
        exitCode: entry.exitCode,
        durationMs: entry.durationMs,
      });
    },
  }),
};

Expected output shape

const result = await agent.run("Fix the failing test...");
// result.output   — description of changes made and test results
// result.steps    — full trace of file reads, writes, and shell commands
// result.cost     — USD cost for the session

Pitfalls

• rm is hard-blocked and cannot be enabled via additionalCommands — use mv to archive files instead
• maxOutputChars: 4000 (default) truncates long command output — increase to 8000+ for bun test on large test suites
• timeoutMs: 30_000 (default) is too short for bun install — set 60_000+ for package management commands
• Always read files before writing them — the agent must understand the existing code structure before making changes
• file-write overwrites the entire file — ensure the agent reads the file first and preserves non-modified sections