Development
AutoCode is a TypeScript OpenCode plugin/library. The plugin entry point is src/plugin.ts, which injects generated skills, loads configuration, derives external-directory permission rules, merges tier-specific agent model settings, registers managed agents, registers managed commands, and exposes runtime tools.
The managed agent catalogue lives in src/agents/index.ts, and prompt templates live under src/agents/prompts/. Commands are registered in src/commands/index.ts, so the published package does not need separate command Markdown files. Generated skills are bundled from source during builds, and scripts/copy-skill-sources.ts copies them into dist/skills.
spy is registered only with an explicitly configured spy tier; balanced does not enable it, and auto requires an explicitly configured smart tier. spy is a primary, visible, read-only safety review and guidance agent for direct use only; it cannot receive session handoff.
Runtime tools live in src/tools/. They cover concepts, design workspace read/write, execution handoff, criteria tracking, read-only database discovery and table reads, REST requests and cached response lookup, sandbox operations, cross-project task execution, and session resume support. Shared tool error handling should stay aligned with src/utils/tools.ts and the agent error rules.
Session and Temporary Workspace Architecture
OpenCode sessions are sole workflow and state source. autocode_session_create requires a nonblank prompt and creates an agent handoff session.
Retained tools create or reuse .agents/jobs/<timestamp>_<session-title-slug>/ on demand through shared utility. This directory holds temporary per-session artifacts only.
Local memory transition artifacts
The active local-memory store is .opencode/autocode/memories/; it starts empty for this transition and runtime creates Markdown .md memory files only through learn. No legacy import, conversion, or seed is performed.
Generated skills
Only bundled AutoCode skills from src/skills ship with plugin. No remote skill acquisition or snapshot packaging. OpenCode loads SKILL.md guidance into agent context.
Runtime extracts missing builtin skills into ~/.agents/skills/autocode/; existing builtin directories stay untouched. Do not delete or modify external/user skill folders.
Local skill build and package validation
- Edit builtin
src/skills/<skill>/SKILL.mdand supporting local assets; retainnameanddescriptionfrontmatter for skill loading. - Build plugin and bundled skills together:
bun run buildscripts/copy-skill-sources.tscopies local release assets intodist/skills, excluding TypeScript and test/spec files.scripts/skill-bundle.tswritesdist/skills/.bundle-manifest.jsonwith directory paths, file paths, and SHA-256 digests.
For asset-only changes after initial build, refresh skills and manifest without rebuilding plugin:bun run copy:skills - Validate existing build before local loading or packaging:
bun run verify:packagescripts/verify-package-artifacts.tschecksdist/plugin.js,dist/plugin.d.ts, package metadata, and exact skill manifest paths/digests. Expected result: exit code0, no errors. Validation does not build missing artifacts. - Use watch mode for bundle/declaration rebuilds:
bun run watch
Skills copy once at watch startup, not on later asset edits. After skill edits, rerunbun run copy:skillsor restart watch; rerunbun run verify:packageafter output completes.
Managed script execution
When agents lack tools, the build their own tools on the fly to complete their tasks. These node script artifacts live at .agents/jobs/YYYY-MM-DD_hh-mm-ss_{title_dir}/scripts. Each scripts project root can contain src/, logs/, package.json, package-lock.json, node_modules/, and services/; these artifacts persist until whole-job cleanup. scripts/src is the canonical managed sourceRoot, fixed by the runtime and never caller input.
Original project remains authoring context; managed Node processes use scripts root as current working directory. Node.js 20 or later and npm are required. Run and service-start entries accept filename-only paths such as task.mjs or nested/task.mjs, relative to fixed sourceRoot. They reject src/-prefixed entries, absolute paths, backslashes, traversal, symlink escapes, broken symlinks, non-files, and extensions other than .mjs. AUTOCODE_SCRIPT_ROOT is scripts root; AUTOCODE_WORKSPACE_ROOT is unchanged.
| Operation or event | Structure, log, and lifecycle behavior |
|---|---|
autocode_script_project | Ensures the directory structure, including logs/, and programmatically generates or refreshes AGENTS.md. Repeated setup preserves existing scripts/ and logs/. |
autocode_script_install | Installs or reconciles dependencies and writes npm reconciliation logs only when reconciliation work occurs. |
autocode_script_run | Runs finite work and writes execution logs, including for failure and timeout. Finite runs clean up on timeout. |
autocode_script_service start | Starts long-running work and creates lifecycle logs; status and stop use the opaque service run_id. Stop services when done. |
| Editing a script | Editing src/*.mjs alone creates no run log. |
Typical finite workflow:
- Prepare project with
autocode_script_project. - Install dependencies with
autocode_script_installusing npm registry version, range, or tag specs only. - Run with
autocode_script_runusingentry, optional stringargv, and optionaltimeout_ms.
For long-running work, use autocode_script_service with action start, status, or stop; service runs use opaque run_id. Finite runs clean up on timeout. Services have managed ownership and lifecycle cleanup; stop a service when done.
Dependencies inherited from ancestor workspaces are resolved there; local dependencies install under script node_modules/. Dependency specs allow npm registry versions, ranges, and tags only. They reject file:, link:, relative or absolute paths, URLs, Git sources, and filesystem or network archive sources. Provenance metadata records dependency source and, where applicable, version, path, workspace, and requested range. npm cache reuse may avoid downloads, but does not mean installed node_modules files are inherited or shared.
Finite runs start a direct Node process; timeout terminates its process group, and complete output is stored under script logs/. Services are Linux-only and have opaque run_id values, owner process-group state under services/, and validated status and stop operations. Callers should explicitly stop services. Terminal events, disposal, and whole-job cleanup stop services owned by that lifecycle.
Sandbox execution
Linux sandbox execution requires usable Bubblewrap (bwrap).
Sandbox tools include autocode_sandbox_create, autocode_sandbox_cli, autocode_sandbox_delete, autocode_sandbox_read, autocode_sandbox_glob, autocode_sandbox_grep, autocode_sandbox_edit, and autocode_sandbox_copy. Sandboxes expose /sandbox for writable work, /home for the sandbox home, and /workspace as a read-only project mount.
Canonical sandbox path is exactly .agents/jobs/YYYY-MM-DD_hh-mm-ss_{title_dir}/sandboxes/{sandbox_name}. Resolve current job first from its linked session; otherwise use deterministic newest timestamped workspace matching current session-title slug. No owner returns an error before filesystem mutation or process spawn. All sandbox access, list, create, copy, and delete operations stay in resolved current job; never look up sandbox names across jobs, so same {sandbox_name} may exist independently in multiple jobs. Never access, fall back to, migrate, scan, delete, or write legacy .agents/sandboxes; legacy data remains untouched and inaccessible.
Process kill scans exclude canonical sandbox trees for valid job workspaces; they still scan all other job-workspace files. Cleanup may remove an empty workspace sandboxes directory, never its job workspace.
Unsupported hosts include macOS, Windows, Android or Termux, non-Linux systems, and Linux systems without usable bwrap or user namespace support. When sandboxing is unsupported, AutoCode disables the sandbox execution agent and force-denies sandbox create, CLI, delete, read, glob, grep, edit, and copy tools.
Local setup
Local setup targets repository development, not public npm installation.
- Install repository dependencies needed for build:
bun install
Dependency versions come frompackage.json. - Build and validate local plugin before loading:
bun run build bun run verify:package
Build preserves the livedistentrypoint, bundlessrc/plugin.ts, emits declarations, and copies bundled local skills intodist/skillswith.bundle-manifest.json. Expected outputs:dist/plugin.js,dist/plugin.d.ts, and validated skill assets. Build does not install shim. - Install local shim so OpenCode loads repository build:
bun run install:shim
Shim path:~/.config/opencode/plugins/autocode.js. - Load plugin in OpenCode through the installed global shim; build must exist first. Do not add a repository-local shim for the same plugin: OpenCode discovers both and rejects the second with
Duplicate plugin ID: autocode. Use/reloadto reload the completed build.
Development commands
| Command | Purpose |
|---|---|
bun run build | Preserves the live entrypoint, bundles plugin, emits declarations, copies bundled local skills, writes manifest. |
bun run copy:skills | Refreshes dist/skills and .bundle-manifest.json from local sources only. |
bun run verify:package | Validates plugin artifacts, package metadata, and skill manifest paths/SHA-256 digests. |
bun run install:shim | Installs local development shim at ~/.config/opencode/plugins/autocode.js. |
bun run watch | Copies skills/manifest once; watches plugin bundle and declarations. Skill edits require recopy or restart. |
bun run test | Runs TypeScript checking, then isolated Bun tests under src. |
bun run tests | Runs isolated Bun tests under src without TypeScript checking. |
bun run typecheck | Runs TypeScript checking without emitting files. |
bun run verify:sandbox-online | Runs sandbox verification script. |
There is no lint script in the current package.json.
Testing
- Check types and local runtime/bundled-skill tests together before committing:
bun run test
Usesbun run typecheckfollowed bybun test src --isolate --reporter=dots. Expected result: no type diagnostics, passing Bun summary. - Run tests alone when type checking already completed:
bun run tests - Check types alone for quick diagnostics:
bun run typecheck
Success exits0with no diagnostics. Built skill assets require separatebun run buildandbun run verify:packagechecks above.
Local Plugin Deployment
Local source workflow only; not npm publish or public npm installation.
- Build and validate distributable output before local deployment:
bun run build bun run verify:package
Outputs:dist/plugin.js, declarations, bundled local skills underdist/skills, anddist/skills/.bundle-manifest.json. Package entry points matchmain,types, andexportsinpackage.json. - Install shim separately so OpenCode loads local build:
bun run install:shim
Shim path:~/.config/opencode/plugins/autocode.js.
See Distribution Guide for public registry distribution.