opencode-titan 0.1.0 → 0.1.1

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,4 +1,9 @@
 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. */

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,5 +1,6 @@
 // src/config/constants.ts
 var TITAN_AGENT_NAME = "titan";
+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. 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>
@@ -51,6 +52,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 +304,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 +321,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 +356,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}`;
@@ -539,14 +547,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 +573,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 +582,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 +599,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.1",
   "description": "Distributed delegation plugin for OpenCode — Titan orchestrator with parallel Myrmidons",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",