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.

Rendering diagram...

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

Builds copy bundled skills and tracked GitHub snapshots into dist/skills, and the plugin can install the generated output for OpenCode under ~/.agents/skills/autocode/ or the equivalent XDG configuration location. Skills are knowledge files that OpenCode loads into AI context so agents and workflows can follow project-specific instructions; users do not need to invoke these files directly.

GitHub skill snapshots

Run bun run skill:sync to refresh GitHub skill snapshots. It uses the primary cache at ~/.cache/autocode/github/<owner>/<project>/ and may falls back to .opencode/autocode/cache/github/<owner>/<project>/ on failure. Both cache trees are disposable and safe to delete. Sync reads src/skills/github.jsonc and writes tracked snapshots to src/skills/github/{owner}/{project}/{skill}. Review every sync change in Git before commit.

Run bun run skill:sync -- --force-refresh to bypass cached repositories and refresh them remotely.

Run bun run build to copy committed skill snapshots from src/skills into dist (the package directory shipped to users). Autocode plugin startup extracts only these local bundled files and never clones, symlinks, or fetches skills.

Legal files retain their original names in github/{owner}/{project}/. Projects under one owner can have different legal files. Sync warns when a repository-root license is missing. Syncing accepts redistribution risk and grants no rights.

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_install using npm registry version, range, or tag specs only.
Run with autocode_script_run using entry, optional string argv, and optional timeout_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 is for repository development only. It is not the public npm installation flow.

Install dependencies from the repository root.
```
bun install
```
Bun installs the dependencies declared in package.json.
Build the plugin.
```
bun run build
```
The build removes dist, bundles src/plugin.ts, emits TypeScript declarations, and copies generated skills and GitHub snapshots into dist/. It does not install the local shim.
Install the local shim when you want OpenCode to load the repository build.
```
bun run install:shim
```
This writes the local development shim to ~/.config/opencode/plugins/autocode.js.
Load the plugin in OpenCode.
For local development in this repository, .opencode/plugin/autocode.ts re-exports the built plugin from dist/plugin.js.

Development commands

Command	Purpose
`bun run skill:sync`	Refreshes tracked GitHub skill snapshots; review Git changes before commit.
`bun run build`	Clears `dist`, bundles `src/plugin.ts`, emits declarations, and copies skill into `dist/skills`.
`bun run install:shim`	Installs the local development shim at `~/.config/opencode/plugins/autocode.js`.
`bun run watch`	Copies generated skills once, then watches source files. When they change, it automatically rebuilds the Bun bundle and declarations.
`bun test`	Runs the Bun test suite under `src`.
`bun run typecheck`	Runs TypeScript type checking without emitting files.
`bun run verify:sandbox-online`	Runs the sandbox verification script.

There is no lint script in the current package.json.

Testing

The repository includes Bun tests for tools and generated skills under src/**/*.test.ts.

bun test

Review the Bun test summary in your terminal to confirm whether the suite passed.

Run TypeScript type checking separately.

bun run typecheck

TypeScript reports diagnostics if type checking fails, and exits successfully when no diagnostics are emitted.

Local Plugin Deployment

Build the distributable plugin only for the local source workflow in this repository, when you are building AutoCode yourself and deploying or testing it locally through the local shim. This is not the npm publish or npm install workflow.

bun run build
bun run install:shim

The build output is written to dist/, including dist/plugin.js, declarations, and copied generated skills under dist/skills, matching the main, types, and exports fields in package.json. Run bun run install:shim separately when you need the local OpenCode shim.

See Distribution Guide for more information about distributing AutoCode on public registries.