normal-swe

1import type { Register } from 'claude-code'
2import { gardener } from './agents/gardener'
3import { librarian } from './agents/librarian'
4import { oracle } from './agents/oracle'
5import { drawEditorRow, editor, hideEditorResult, reviseDraft } from './tools/editor'
6
7export const AGENT_NOT_REGISTERED = 'normal-swe could not register the agent'
8
9const AGENTS = [oracle, librarian, gardener]
10
11export const register: Register = (on) => {
12  on('session.start', async ($, e, next) => {
13    await $.tool.register(editor)
14
15    // A hook that throws is skipped whole, so one failed agent must not cost the others.
16    for (const agent of AGENTS) {
17      try {
18        await $.agent.register({
19          ...agent,
20          prompt: await $.fs.read(`${$.plugin.root}/prompts/${agent.name}.md`),
21        })
22      } catch (error) {
23        $.ui.log(`${AGENT_NOT_REGISTERED} ${agent.name}: ${error}`)
24      }
25    }
26
27    return next(e)
28  })
29
30  on('tool.call', { tool: 'mcp__normal-swe__editor' }, reviseDraft)
31  on(
32    'ui.render',
33    { component: 'ToolUse', props: { tool: 'mcp__normal-swe__editor' } },
34    drawEditorRow,
35  )
36  on(
37    'ui.render',
38    { component: 'ToolResult', props: { tool: 'mcp__normal-swe__editor' } },
39    hideEditorResult,
40  )
41}
42

1import type { AgentSpec } from 'claude-code'
2
3// The system prompt is prompts/gardener.md.
4export const gardener = {
5  name: 'gardener',
6  description:
7    'Investigates existing code and proposes concrete improvements to its design, maintainability, and testability. Use for substantial structural or maintainability analysis.',
8  model: 'sonnet',
9  effort: 'high',
10  tools: ['Read', 'Glob', 'Grep', 'Edit', 'Write', 'Bash', 'WebSearch', 'WebFetch'],
11} satisfies Omit<AgentSpec, 'prompt'>
12

1import type { AgentSpec } from 'claude-code'
2
3// The system prompt is prompts/librarian.md.
4export const librarian = {
5  name: 'librarian',
6  description:
7    'Researches code in local workspaces and external repositories. Use for multi-step code discovery, behavior and architecture questions, dependency research, and commit history. Use direct reads or rg for known paths and exact symbols.',
8  model: 'sonnet',
9  effort: 'high',
10  tools: ['Read', 'Glob', 'Grep', 'Bash', 'WebSearch', 'WebFetch'],
11} satisfies Omit<AgentSpec, 'prompt'>
12

1import type { AgentSpec } from 'claude-code'
2
3// The system prompt is prompts/oracle.md.
4export const oracle = {
5  name: 'oracle',
6  description:
7    'Read-only expert advisor for focused code reviews, difficult debugging, and consequential architecture questions. Use when explicitly requested or when direct investigation leaves a specific high-impact question unresolved.',
8  model: 'fable',
9  effort: 'high',
10  tools: ['Read', 'Glob', 'Grep', 'Bash'],
11} satisfies Omit<AgentSpec, 'prompt'>
12

1import type { MatchedHook, ToolSpec } from 'claude-code'
2
3export const MISSING_TASK =
4  'The editor tool needs a `task` containing the full draft text to revise, plus the intended audience, tone, and constraints. Editor cannot read files, URLs, or this conversation, so paste the contents instead of a path or reference.'
5
6export const editor = {
7  name: 'editor',
8  description:
9    'Revise a supplied draft with Editor, using Opus at low effort. It improves sentence and paragraph structure and removes AI writing patterns while preserving meaning. Supply the draft and a self-contained brief. Editor has no tools, file access, or conversation history. It returns the revised text, followed by any notes after a line containing `--- Editor notes ---`. The caller reads files and applies edits.',
10  inputSchema: {
11    type: 'object',
12    properties: {
13      task: {
14        type: 'string',
15        minLength: 1,
16        description:
17          'The draft text, intended audience, requested tone, constraints, and any supporting context or source excerpts. Include the contents to revise, not just file paths or URLs.',
18      },
19    },
20    required: ['task'],
21    additionalProperties: false,
22  },
23} satisfies ToolSpec
24
25// Answers calls to the editor tool, with prompts/editor.md as the system prompt.
26export const reviseDraft: MatchedHook<'tool.call', { tool: 'mcp__normal-swe__editor' }> = async (
27  $,
28  e,
29) => {
30  if (typeof e.task !== 'string' || !e.task.trim()) {
31    return { deny: MISSING_TASK }
32  }
33
34  const reply = await $.model.complete({
35    model: 'opus',
36    effort: 'low',
37    maxTokens: 32000,
38    system: await $.fs.read(`${$.plugin.root}/prompts/editor.md`),
39    prompt: e.task,
40  })
41
42  return reply.isAnswered ? { result: reply.text } : { deny: `Editor failed: ${reply.reason}` }
43}
44
45type EditorRow = { isRunning: boolean; isErrored: boolean; isInterrupted: boolean }
46
47// Draws the editor's transcript row as one dim line, spaced and indented like the engine's folded
48// tool rows, so the draft never fills the screen. The transcript still stores the call whole.
49export const drawEditorRow: MatchedHook<
50  'ui.render',
51  { component: 'ToolUse'; props: { tool: 'mcp__normal-swe__editor' } }
52> = ($, e) => ({
53  type: 'Box',
54  props: { marginTop: 1, marginLeft: 2 },
55  children: [{ type: 'Text', props: { dimColor: true }, children: [describeEditorRow(e.props)] }],
56})
57
58// Draws nothing under the editor's row: the caller applies the revision, so the transcript need
59// not show it. The model still reads the full result. A failure's reason is drawn as the engine
60// draws any tool's, since nothing else on the screen says why the Editor did not answer.
61export const hideEditorResult: MatchedHook<
62  'ui.render',
63  { component: 'ToolResult'; props: { tool: 'mcp__normal-swe__editor' } }
64> = ($, e, next) => (e.props.isErrored ? next(e) : { type: 'Box', props: { display: 'none' } })
65
66export function describeEditorRow({ isRunning, isErrored, isInterrupted }: EditorRow): string {
67  if (isInterrupted) return 'The Editor was interrupted.'
68  if (isErrored) return 'The Editor could not revise the draft.'
69  if (isRunning) return 'Asking the Editor to revise a draft…'
70  return 'Asked the Editor to revise a draft.'
71}
72