opencode-preflight

Project-configurable startup preflight prompts for OpenCode.

繁體中文

This package is a local proof of concept for an OpenCode plugin that builds a startup prompt from project-local configuration. It can inspect git state, branch rules, path conditions, time windows, action prompt files, JSON-file memory, and action run state before presenting available startup actions.

Install

Run the initializer from your target project:

npx @arthurhuang09/opencode-preflight init

This creates .opencode/opencode.json, .opencode/package.json, and .opencode/plugins/preflight.js, then installs the npm package under .opencode. It also registers /preflight-config, /preflight-action-list, /preflight-action-run, and /preflight-action-edit. The shim-based install avoids OpenCode npm plugin loader issues with scoped packages while still using the published npm package.

To also create the default preflight action files immediately:

npx @arthurhuang09/opencode-preflight init --with-config

To create only specific default actions:

npx @arthurhuang09/opencode-preflight init --with-config --actions=project-readiness,task-progress-review

For local development of this repository:

npm install

Usage

1. Run npx @arthurhuang09/opencode-preflight init in the target project.
2. Start OpenCode in that project.
3. Run /preflight-config from an active session, choose which default actions to create, or ask OpenCode to call the preflight_config tool.
4. Review the generated .opencode/preflight.jsonc and .opencode/preflight/* files.
5. Restart or open a new OpenCode session in that project.

When a configured trigger matches, the plugin creates a Startup Preflight session and asks which configured action to run. Actions marked ask-before-execute require user confirmation before commands or file edits.

From an active session, use /preflight-action-list to inspect matched triggers, configured actions, availability, and warnings. Use /preflight-action-run to choose one currently available action; actions suppressed by run state are not offered as runnable options. Use /preflight-action-edit to adjust one action's behavior, prompt file, run state, memory, and trigger references.

Set OPENCODE_PREFLIGHT_AUTOSTART=0 to disable automatic startup sessions while keeping the tool and system prompt integration available.

Usage Scenarios

• Default branch startup: when OpenCode starts on main or master, ask whether to review issues, check project readiness, or skip for now.
• Feature branch resume: when OpenCode starts on a non-default branch, summarize recent commits, worktree changes, and likely next steps before asking what to continue.
• Daily or hourly routines: use time triggers to show recurring actions such as standup prep, issue triage, or dependency checks only during a configured time window.
• Project-specific readiness: require files such as package.json, AGENTS.md, or deployment config to exist before offering a startup checklist.
• Memory-backed follow-up: load JSON-file memory topics so repeated issue reviews can remember items waiting on user replies, external replies, or closure.
• Noise reduction: use runState.skipIfLastRunWithinHours so routine prompts do not appear again too soon after they were already shown.

Commands

npm run lint
npm run typecheck
npm test
npm run build
node --test test/engine.test.js

lint and typecheck use node --check for JavaScript syntax checks. build runs npm pack --dry-run to verify package contents. There is no configured formatter.

Package Entrypoints

• src/index.js is the default OpenCode plugin entrypoint.
• src/engine.js is exported as opencode-preflight/engine for the preflight engine.
• src/tui.js registers the /preflight-config, /preflight-action-list, and /preflight-action-run TUI commands.

How It Works

The engine reads .opencode/preflight.jsonc from the active project. When a trigger matches, it loads the configured actions, action prompt files, and memory topics, then composes an OpenCode startup prompt.

Supported trigger inputs include:

• git availability, worktree status, dirty state, and branch rules
• required or missing project paths
• day and time windows with optional timezone

Supported action inputs include:

• promptFile content
• memory.read topics backed by JSON files
• runState rules that can skip recently prompted actions

Configure A Project

Use the plugin tool preflight_config or the /preflight-config command to create the default project-local files:

.opencode/preflight.jsonc
.opencode/preflight/actions/issue-review.md
.opencode/preflight/actions/issue-memory.md
.opencode/preflight/actions/project-readiness.md
.opencode/preflight/actions/task-progress-review.md
.opencode/preflight/memory.json

The tool does not overwrite existing files unless force: true is passed.

The default action templates are selectable: issue-review, project-readiness, and task-progress-review. If no action list is provided, all default templates are created.

Manual Install

If you do not want to use npx, create these files yourself.

.opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "preflight-config": {
      "description": "Create or repair OpenCode preflight config files",
      "template": "Ask which default OpenCode preflight actions to create: issue-review, project-readiness, task-progress-review, or all. Then call the preflight_config tool with the selected action ids. Do not overwrite existing files unless I confirm, then list created and skipped files."
    },
    "preflight-action-list": {
      "description": "List configured preflight actions and current status",
      "template": "Call the preflight_action_list tool and summarize the configured OpenCode preflight actions. This is status-only; do not run an action or ask me to choose one."
    },
    "preflight-action-run": {
      "description": "Choose and run an available preflight action",
      "template": "Call the preflight_action_list tool. If no actions are available, explain why and do not ask me to choose one. Otherwise use AskUserQuestion/question with the available action ids and `Do not run anything for now`. After I choose an action, call the preflight_action_prompt tool with that action id, then follow the returned prompt. For ask-before-execute actions, confirm before commands or edits."
    },
    "preflight-action-edit": {
      "description": "Edit a configured preflight action and its triggers",
      "template": "Help me edit one configured OpenCode preflight action. First read `.opencode/preflight.jsonc` and list the configured action ids. Ask which action to edit and what to change: behavior, prompt file, runState, memory, or trigger conditions/references. Then update only the relevant `.opencode/preflight.jsonc` fields and action prompt file. Do not run the action. After editing, summarize the changed files and behavior."
    }
  }
}

.opencode/package.json:

{
  "type": "module",
  "dependencies": {
    "@arthurhuang09/opencode-preflight": "latest"
  }
}

.opencode/plugins/preflight.js:

import preflight from "@arthurhuang09/opencode-preflight";

export default preflight;

Then run npm install inside .opencode.

TUI Commands

• /preflight-config creates or repairs project-local preflight configuration files.
• /preflight-action-list lists matched triggers, configured actions, run-state availability, and warnings.
• /preflight-action-run asks which currently available action to run. If no action is available, it explains why and does not ask for an impossible choice.
• /preflight-action-edit edits one configured action's behavior, prompt file, run state, memory, and trigger references without running it.

Autostart Behavior

Autostart is skipped when OPENCODE_PREFLIGHT_AUTOSTART=0 is set, or when OpenCode was launched with -s, --session, or --session=....

Startup prompt injection uses the OpenCode SDK v2 transport exposed as client._client; if that transport is unavailable, injection is a no-op.

Tests

Tests use node:test and create isolated temporary projects with .opencode/preflight fixtures. buildPreflight() records run state by default, so tests that need repeatable prompts should pass { recordRunState: false } or use a fresh temp project.