opencode-titan 0.1.0 → 0.1.2

package/README.md

@@ -1,6 +1,9 @@
 <div align="center">
   <h3>⚡ opencode-titan ⚡</h3>
 
+  <img src="assets/titan-demo.gif" alt="opencode-titan demo" width="100%">
+
+
   <p><i>One mind that never touches the keyboard. A fleet of hands that never stops moving.<br>Plan with the slow, expensive genius, and let the fast ones build in parallel.</i></p>
 
   <p><b>OpenCode Orchestration Plugin</b> · Mix any models · Delegate everything · Run in parallel</p>
@@ -32,8 +35,30 @@ The plugin builds a two-tier hierarchy of agents:
 
 ## Installation
 
-> [!NOTE]
-> This plugin is not published to npm yet, so install it manually from source. npm/Bun package installation is coming soon.
+Add the [`opencode-titan`](https://www.npmjs.com/package/opencode-titan) package to the `plugin` array in your OpenCode config (`opencode.json`). OpenCode installs it automatically from npm on startup:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-titan"]
+}
+```
+
+To pin a specific version, append it with `@`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-titan@0.1.0"]
+}
+```
+
+Restart OpenCode and Titan becomes your default agent.
+
+<details>
+<summary><b>Alternative: install from source</b></summary>
+
+Use this if you want to hack on the plugin or run an unreleased version.
 
 **1. Clone and build the plugin:**
 
@@ -59,6 +84,8 @@ OpenCode treats any plugin entry starting with `.`, `file://`, or an absolute pa
 
 Restart OpenCode and Titan becomes your default agent.
 
+</details>
+
 ## Getting Started
 
 1. **Create your plugin config** at `~/.config/opencode/opencode-titan.jsonc`
@@ -120,7 +147,7 @@ Titan is the most intelligent agent in the fleet, and by far the slowest and mos
 
 ### ⚙️ Myrmidons — The Fleet
 
-Myrmidons are the hands. Each executes a delegated task and reports back concisely — responses to Titan are enforced to a single paragraph, 500 words max, keeping Titan's context lean. Every Myrmidon declares a `modelType` that shapes how Titan routes work to it:
+Myrmidons are the hands. Each executes a delegated task and reports back concisely — responses to Titan are enforced to a single paragraph, 1000 words max by default (configurable via `maxResponseWords`), keeping Titan's context lean. Every Myrmidon declares a `modelType` that shapes how Titan routes work to it:
 
 <table>
   <tr>
@@ -172,6 +199,7 @@ Myrmidons are the hands. Each executes a delegated task and reports back concise
 | `myrmidons` | `array` | The Myrmidon fleet (see above) |
 | `children` | `array` | **Deprecated** alias for `myrmidons`, kept for backwards compatibility. Prefer `myrmidons`; if both are set, `myrmidons` wins |
 | `disabled_tools` | `string[]` | Tool names to disable for the plugin's agents |
+| `maxResponseWords` | `number` (≥1) | Max word count enforced on each Myrmidon's one-paragraph response to Titan (default: `1000`) |
 | `backgroundJobs.maxSessionsPerAgent` | `number` (1–10) | Max concurrent sessions per agent (default: `10`) |
 
 ### Config Locations

package/dist/agents/myrmidon.d.ts

@@ -1,6 +1,6 @@
-import type { MyrmidonConfig } from '../config';
+import { type MyrmidonConfig } from '../config';
 import type { AgentDefinition } from './titan';
-export declare function createMyrmidonAgent(index: number, config: MyrmidonConfig): AgentDefinition;
+export declare function createMyrmidonAgent(index: number, config: MyrmidonConfig, maxResponseWords?: number): AgentDefinition;
 /**
  * @deprecated Use `createMyrmidonAgent`. Retained as a backwards-compatible
  * alias for the former "child agent" naming.

package/dist/agents/titan.d.ts

@@ -13,5 +13,5 @@ export declare function resolvePrompt(base: string, customPrompt?: string, custo
 /**
  * Build the Titan prompt with Myrmidon descriptions dynamically injected.
  */
-export declare function buildTitanPrompt(myrmidons: MyrmidonConfig[]): string;
-export declare function createTitanAgent(myrmidons: MyrmidonConfig[], model?: string, customPrompt?: string, customAppendPrompt?: string): AgentDefinition;
+export declare function buildTitanPrompt(myrmidons: MyrmidonConfig[], maxResponseWords?: number): string;
+export declare function createTitanAgent(myrmidons: MyrmidonConfig[], model?: string, customPrompt?: string, customAppendPrompt?: string, maxResponseWords?: number): AgentDefinition;

package/dist/config/constants.d.ts

@@ -1,9 +1,14 @@
 export declare const TITAN_AGENT_NAME: "titan";
+/**
+ * Default maximum word count enforced on a Myrmidon's final response to Titan.
+ * Overridable via the `maxResponseWords` plugin config key.
+ */
+export declare const DEFAULT_MAX_RESPONSE_WORDS: 1000;
 export declare const ALL_AGENT_NAMES: readonly ["titan"];
 export type AgentName = (typeof ALL_AGENT_NAMES)[number];
 /** Agents that cannot be disabled. */
 export declare const PROTECTED_AGENTS: Set<"titan">;
-export declare const DELEGATION_REMINDER = "<internal_reminder>DELEGATE EVERYTHING POSSIBLE TO MYRMIDONS. You are the slowest agent by far - your only job is planning, routing, and synthesizing results. Never do work a Myrmidon can handle. Parallelize aggressively: tool calls made in the SAME response turn run concurrently \u2014 always batch all ready task() dispatches into ONE response, never one per turn. SAY WHAT YOU DO: if you announce launching N Myrmidons, emit exactly N task() calls in that same response \u2014 never announce multiple then dispatch only one. Before ending a dispatch turn, count your task() calls and confirm they match the number of Myrmidons you named. The task() tool takes only subagent_type, description, and prompt \u2014 never pass any other parameters. </internal_reminder>";
+export declare const DELEGATION_REMINDER = "<internal_reminder>DELEGATE EVERYTHING POSSIBLE TO MYRMIDONS. You are the slowest agent by far - your only job is planning, routing, and synthesizing results. Never do work a Myrmidon can handle. THE ONE EXCEPTION: context-bound synthesis. If a task's input is your OWN accumulated context \u2014 findings you gathered, results Myrmidons reported back, reasoning built up this session \u2014 do it YOURSELF. Delegating a summary/report/plan/file of what you found or decided strips the context the task needs (Myrmidons start blank), so the write-up stays with you. Parallelize aggressively: tool calls made in the SAME response turn run concurrently \u2014 always batch all ready task() dispatches into ONE response, never one per turn. SAY WHAT YOU DO: if you announce launching N Myrmidons, emit exactly N task() calls in that same response \u2014 never announce multiple then dispatch only one. Before ending a dispatch turn, count your task() calls and confirm they match the number of Myrmidons you named. The task() tool takes only subagent_type, description, and prompt \u2014 never pass any other parameters. </internal_reminder>";
 /**
  * Sentinel substring used to detect whether {@link DELEGATION_REMINDER} has
  * already been injected into a system prompt, avoiding double-injection.
@@ -18,4 +23,4 @@ export declare const DELEGATION_REMINDER_SENTINEL = "DELEGATE EVERYTHING POSSIBL
  * at the point of each new user message keeps that behavior consistent — it
  * mimics the user manually prefixing "delegate this" onto every ask.
  */
-export declare const PER_MESSAGE_DELEGATION_REMINDER = "<delegation_directive>\nBefore you act on the user's message above, STOP and route it through delegation first.\n\n1. Decompose the request (including any follow-up tweaks, fixes, or refinements to prior work) into concrete units of work.\n2. For every unit that would require even a SINGLE tool call \u2014 reading/searching/editing files, running commands, testing, validating, looking things up, gathering information, or any mechanical work \u2014 you MUST delegate it to Myrmidons via task(). This applies to small iterative changes on the existing task just as much as to brand-new work. Do NOT do it yourself because it \"seems quick.\"\n3. Dispatch all independent units in parallel: emit one task() call per unit in a SINGLE response, and make the number of task() calls match the number of Myrmidons you announce.\n4. The ONLY time you may answer directly without delegating is when the request is trivially simple, purely conversational, and requires zero tool calls (e.g., clarifying a question, restating a plan, a one-word answer). When in doubt, delegate.\n\nTreat this as if the user explicitly said: \"delegate this to your Myrmidons.\"\n</delegation_directive>";
+export declare const PER_MESSAGE_DELEGATION_REMINDER = "<delegation_directive>\nBefore you act on the user's message above, STOP and route it through delegation first.\n\n1. Decompose the request (including any follow-up tweaks, fixes, or refinements to prior work) into concrete units of work.\n2. For every unit that would require even a SINGLE tool call \u2014 reading/searching/editing files, running commands, testing, validating, looking things up, gathering information, or any mechanical work \u2014 you MUST delegate it to Myrmidons via task(). This applies to small iterative changes on the existing task just as much as to brand-new work. Do NOT do it yourself because it \"seems quick.\"\n3. EXCEPTION \u2014 context-bound synthesis: if a unit's real input is YOUR OWN accumulated context (findings you gathered, results your Myrmidons already reported back, reasoning or decisions from earlier in this session) and the deliverable is just expressing/organizing/persisting that context \u2014 e.g. writing a summary, report, plan, or markdown file of what was found/decided \u2014 do it YOURSELF. Delegating it would hand a blank-context Myrmidon a task it cannot do correctly, losing the very information the deliverable depends on. Writing a file is one cheap tool call; never delegate it just to avoid that call. You may still delegate any fresh lookups the write-up needs, but the context-bearing synthesis stays with you.\n4. Dispatch all independent units in parallel: emit one task() call per unit in a SINGLE response, and make the number of task() calls match the number of Myrmidons you announce.\n5. The ONLY time you may answer directly without delegating is when the request is trivially simple, purely conversational, and requires zero tool calls (e.g., clarifying a question, restating a plan, a one-word answer), OR when it is context-bound synthesis per point 3. When in doubt about fresh work, delegate; when in doubt about whether the task needs context only you hold, keep it.\n\nTreat this as if the user explicitly said: \"delegate this to your Myrmidons.\"\n</delegation_directive>";

package/dist/config/schema.d.ts

@@ -85,6 +85,7 @@ export declare const PluginConfigSchema: z.ZodObject<{
         displayName: z.ZodOptional<z.ZodString>;
         provider: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>>;
+    maxResponseWords: z.ZodOptional<z.ZodNumber>;
     disabled_tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
     backgroundJobs: z.ZodOptional<z.ZodObject<{
         maxSessionsPerAgent: z.ZodDefault<z.ZodNumber>;

package/dist/index.js

@@ -1,14 +1,16 @@
 // src/config/constants.ts
 var TITAN_AGENT_NAME = "titan";
-var DELEGATION_REMINDER = `<internal_reminder>DELEGATE EVERYTHING POSSIBLE TO MYRMIDONS. You are the slowest agent by far - your only job is planning, routing, and synthesizing results. Never do work a Myrmidon can handle. Parallelize aggressively: tool calls made in the SAME response turn run concurrently \u2014 always batch all ready task() dispatches into ONE response, never one per turn. SAY WHAT YOU DO: if you announce launching N Myrmidons, emit exactly N task() calls in that same response \u2014 never announce multiple then dispatch only one. Before ending a dispatch turn, count your task() calls and confirm they match the number of Myrmidons you named. The task() tool takes only subagent_type, description, and prompt \u2014 never pass any other parameters. </internal_reminder>`;
+var DEFAULT_MAX_RESPONSE_WORDS = 1e3;
+var DELEGATION_REMINDER = `<internal_reminder>DELEGATE EVERYTHING POSSIBLE TO MYRMIDONS. You are the slowest agent by far - your only job is planning, routing, and synthesizing results. Never do work a Myrmidon can handle. THE ONE EXCEPTION: context-bound synthesis. If a task's input is your OWN accumulated context \u2014 findings you gathered, results Myrmidons reported back, reasoning built up this session \u2014 do it YOURSELF. Delegating a summary/report/plan/file of what you found or decided strips the context the task needs (Myrmidons start blank), so the write-up stays with you. Parallelize aggressively: tool calls made in the SAME response turn run concurrently \u2014 always batch all ready task() dispatches into ONE response, never one per turn. SAY WHAT YOU DO: if you announce launching N Myrmidons, emit exactly N task() calls in that same response \u2014 never announce multiple then dispatch only one. Before ending a dispatch turn, count your task() calls and confirm they match the number of Myrmidons you named. The task() tool takes only subagent_type, description, and prompt \u2014 never pass any other parameters. </internal_reminder>`;
 var DELEGATION_REMINDER_SENTINEL = "DELEGATE EVERYTHING POSSIBLE TO MYRMIDONS";
 var PER_MESSAGE_DELEGATION_REMINDER = `<delegation_directive>
 Before you act on the user's message above, STOP and route it through delegation first.
 
 1. Decompose the request (including any follow-up tweaks, fixes, or refinements to prior work) into concrete units of work.
 2. For every unit that would require even a SINGLE tool call \u2014 reading/searching/editing files, running commands, testing, validating, looking things up, gathering information, or any mechanical work \u2014 you MUST delegate it to Myrmidons via task(). This applies to small iterative changes on the existing task just as much as to brand-new work. Do NOT do it yourself because it "seems quick."
-3. Dispatch all independent units in parallel: emit one task() call per unit in a SINGLE response, and make the number of task() calls match the number of Myrmidons you announce.
-4. The ONLY time you may answer directly without delegating is when the request is trivially simple, purely conversational, and requires zero tool calls (e.g., clarifying a question, restating a plan, a one-word answer). When in doubt, delegate.
+3. EXCEPTION \u2014 context-bound synthesis: if a unit's real input is YOUR OWN accumulated context (findings you gathered, results your Myrmidons already reported back, reasoning or decisions from earlier in this session) and the deliverable is just expressing/organizing/persisting that context \u2014 e.g. writing a summary, report, plan, or markdown file of what was found/decided \u2014 do it YOURSELF. Delegating it would hand a blank-context Myrmidon a task it cannot do correctly, losing the very information the deliverable depends on. Writing a file is one cheap tool call; never delegate it just to avoid that call. You may still delegate any fresh lookups the write-up needs, but the context-bearing synthesis stays with you.
+4. Dispatch all independent units in parallel: emit one task() call per unit in a SINGLE response, and make the number of task() calls match the number of Myrmidons you announce.
+5. The ONLY time you may answer directly without delegating is when the request is trivially simple, purely conversational, and requires zero tool calls (e.g., clarifying a question, restating a plan, a one-word answer), OR when it is context-bound synthesis per point 3. When in doubt about fresh work, delegate; when in doubt about whether the task needs context only you hold, keep it.
 
 Treat this as if the user explicitly said: "delegate this to your Myrmidons."
 </delegation_directive>`;
@@ -51,6 +53,9 @@ var PluginConfigSchema = z.object({
   // Deprecated alias for `myrmidons`, retained for backwards compatibility.
   // If both are present, `myrmidons` takes precedence.
   children: z.array(MyrmidonConfigSchema).optional(),
+  // Maximum word count enforced on each Myrmidon's final response to Titan.
+  // Keeps Titan's context lean. Defaults to DEFAULT_MAX_RESPONSE_WORDS (1000).
+  maxResponseWords: z.number().int().min(1).optional(),
   disabled_tools: z.array(z.string()).optional(),
   backgroundJobs: z.object({
     maxSessionsPerAgent: z.number().int().min(1).max(10).default(10)
@@ -300,7 +305,7 @@ You are operating with a hard context budget. Exceeding it causes failure. Follo
 </ContextBudget>
 
 <OutputConstraints>
-- **CRITICAL: Your final response to Titan MUST be ONE PARAGRAPH, no more than 500 words.**
+- **CRITICAL: Your final response to Titan MUST be ONE PARAGRAPH, no more than {{MAX_WORDS}} words.**
 - No preamble, no summary of what you did \u2014 just the results.
 - Report success/failure clearly in your first sentence.
 - Include only actionable details: file paths, line numbers, errors, generated code snippets.
@@ -317,10 +322,14 @@ You are operating with a hard context budget. Exceeding it causes failure. Follo
 {{TASK_PROMPT}}
 </Task>
 `;
-function createMyrmidonAgent(index, config) {
+function createMyrmidonAgent(index, config, maxResponseWords = DEFAULT_MAX_RESPONSE_WORDS) {
   const name = `myrmidon-${index}`;
   const modelTypeHint = config.modelType === "dense" ? "You are running a dense model \u2014 you excel at logic, reasoning, and complex problem-solving. Use this strength for tasks requiring careful analysis." : "You are running a sparse model \u2014 you excel at fast information gathering, broad search, and rapid lookups. Use this strength for research and exploration tasks.";
-  const prompt = `${MYRMIDON_PROMPT_TEMPLATE.replace("{{TASK_PROMPT}}", "")}
+  const template = MYRMIDON_PROMPT_TEMPLATE.replace(
+    "{{MAX_WORDS}}",
+    String(maxResponseWords)
+  );
+  const prompt = `${template.replace("{{TASK_PROMPT}}", "")}
 
 ${modelTypeHint}`;
   return {
@@ -348,7 +357,7 @@ function resolvePrompt(base, customPrompt, customAppendPrompt) {
 
 ${customAppendPrompt}` : effectiveBase;
 }
-function buildTitanPrompt(myrmidons) {
+function buildTitanPrompt(myrmidons, maxResponseWords = DEFAULT_MAX_RESPONSE_WORDS) {
   const resolveProvider = resolveMyrmidonProvider;
   const myrmidonDescriptions = myrmidons.map((myrmidon, idx) => {
     const name = `myrmidon-${idx}`;
@@ -430,7 +439,7 @@ ${selfParallelMyrmidons.join("\n")}` : ""}
 
 <DelegationPhilosophy>
 ## The Golden Rule
-If a task can be abstracted away to a Myrmidon, it MUST be. No exceptions. This includes:
+If a task can be abstracted away to a Myrmidon, it MUST be. The only exception is context-bound synthesis (see below). This includes:
 - Looking up things in the code
 - Testing ideas
 - Writing code
@@ -441,6 +450,26 @@ If a task can be abstracted away to a Myrmidon, it MUST be. No exceptions. This
 - Any information gathering
 - Any mechanical implementation
 
+## The One Exception: Context-Bound Synthesis
+Delegation works by handing a Myrmidon a self-contained task. A Myrmidon starts with a BLANK context \u2014 it sees only the prompt you give it, never your conversation history, never the results your other Myrmidons reported back to you, never the reasoning you've accumulated across this session.
+
+Therefore, there is exactly one class of work you must do YOURSELF: **tasks whose actual input is your own accumulated context.** If completing the task requires knowledge that lives only in your head \u2014 the findings you gathered, the results Myrmidons already reported, the analysis you synthesized, the decisions made earlier in this conversation \u2014 then delegating it would strip away the very information the task needs. The Myrmidon would produce a hollow, wrong, or generic result.
+
+Concrete examples you MUST handle yourself (do not delegate these):
+- Writing a summary, report, or markdown file of findings YOU discovered during this task
+- Writing a plan document that reflects the reasoning and context YOU built up
+- Synthesizing or consolidating results that multiple Myrmidons reported back to you
+- Answering a question that depends on what was already discussed or discovered in this session
+- Any "write down / capture / summarize what we found/decided/did" request
+
+The mechanical distinction:
+- **Does the task need NEW information or NEW work from the codebase/web/tools?** \u2192 Delegate. (The Myrmidon gathers it fresh.)
+- **Is the task's input ALREADY in your context, and the deliverable is just expressing/organizing/persisting it?** \u2192 Do it yourself. Delegating would only lose that context.
+
+When you do produce such a deliverable yourself, you may still delegate the *mechanical* sub-parts you don't have context for. E.g., you write the summary from your own findings, but if you need one extra fact verified you delegate just that verification. The context-bearing synthesis stays with you; the fresh lookups go to Myrmidons.
+
+Writing a file is a single tool call \u2014 cheap. Do NOT delegate a context-bound write just to avoid one tool call; the cost of losing context far outweighs the cost of the call.
+
 ## Parallelization is Key
 You are slow. Your Myrmidons are fast \u2014 sometimes 50x faster. You have **${myrmidons.length} Myrmidon${myrmidons.length !== 1 ? "s" : ""}**. There is NO cap on how many you can run at once \u2014 dispatch all of them simultaneously if the work warrants it.
 
@@ -520,7 +549,7 @@ Before you finish a dispatch turn, silently count: "Independent tasks ready = N.
 Each task() call returns the Myrmidon's result when it completes. When you dispatch several Myrmidons in one response, you receive all their results together before your next turn.
 
 ## 5. Synthesize
-When Myrmidons report back, integrate their results into a coherent outcome. If something is missing or wrong, re-delegate \u2014 don't do it yourself.
+When Myrmidons report back, integrate their results into a coherent outcome. If something is missing or wrong, re-delegate \u2014 don't do it yourself. **But synthesis itself \u2014 consolidating multiple Myrmidons' results, and writing any summary/report/plan/file that captures findings or reasoning you accumulated \u2014 is YOUR job (see "The One Exception: Context-Bound Synthesis"). Never delegate the write-up of context that lives only in your head; the Myrmidon would start blank and lose it.
 
 ## 6. Verify
 Use a Myrmidon to run checks/diagnostics/validations. Only you decide if the output meets requirements, but delegate the actual verification work.
@@ -539,14 +568,14 @@ When delegating to a Myrmidon:
 - Be specific about the task and expected output format
 - Reference file paths/lines, don't paste full contents
 - Set clear boundaries: what to do and what not to do
-- Tell the Myrmidon to report back concisely (one paragraph, under 500 words max)
+- Tell the Myrmidon to report back concisely (one paragraph, under ${maxResponseWords} words max)
 </CommunicationWithMyrmidons>
 
 ${DELEGATION_REMINDER}
 `;
 }
-function createTitanAgent(myrmidons, model, customPrompt, customAppendPrompt) {
-  const basePrompt = buildTitanPrompt(myrmidons);
+function createTitanAgent(myrmidons, model, customPrompt, customAppendPrompt, maxResponseWords = DEFAULT_MAX_RESPONSE_WORDS) {
+  const basePrompt = buildTitanPrompt(myrmidons, maxResponseWords);
   const prompt = resolvePrompt(basePrompt, customPrompt, customAppendPrompt);
   const definition = {
     name: "titan",
@@ -565,6 +594,7 @@ function createTitanAgent(myrmidons, model, customPrompt, customAppendPrompt) {
 // src/agents/index.ts
 function createAgents(config, options) {
   const myrmidons = getMyrmidonConfigs(config);
+  const maxResponseWords = config?.maxResponseWords ?? DEFAULT_MAX_RESPONSE_WORDS;
   const titanModel = config?.titan?.model;
   const titanPrompts = loadAgentPrompt("titan", {
     projectDirectory: options?.projectDirectory
@@ -573,7 +603,8 @@ function createAgents(config, options) {
     myrmidons,
     typeof titanModel === "string" ? titanModel : void 0,
     config?.titan?.prompt,
-    void 0
+    void 0,
+    maxResponseWords
   );
   titan.config.prompt = resolvePrompt(
     titan.config.prompt ?? "",
@@ -589,7 +620,7 @@ function createAgents(config, options) {
     }
   }
   const myrmidonAgents = myrmidons.map(
-    (myrmidonConfig, idx) => createMyrmidonAgent(idx, myrmidonConfig)
+    (myrmidonConfig, idx) => createMyrmidonAgent(idx, myrmidonConfig, maxResponseWords)
   );
   const aliasAgents = myrmidonAgents.map((agent, idx) => ({
     ...agent,

package/opencode-titan.schema.json

@@ -41,6 +41,12 @@
         "$ref": "#/$defs/myrmidon"
       }
     },
+    "maxResponseWords": {
+      "type": "integer",
+      "minimum": 1,
+      "default": 1000,
+      "description": "Maximum word count enforced on each Myrmidon's final (one-paragraph) response to Titan. Keeps Titan's context lean. Defaults to 1000."
+    },
     "disabled_tools": {
       "type": "array",
       "description": "Tool names to disable completely. Disabled tools are not registered with OpenCode.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-titan",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Distributed delegation plugin for OpenCode — Titan orchestrator with parallel Myrmidons",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",