savant-code 0.0.17 → 0.0.19

package/common/src/templates/initial-agents-dir/README.md

@@ -0,0 +1,314 @@
+# Custom Agents
+
+Create specialized agent workflows that coordinate multiple AI agents to tackle complex engineering tasks. Instead of a
+single agent trying to handle everything, you can orchestrate teams of focused specialists that work together.
+
+## Getting Started
+
+1. **Edit an existing agent**: Start with `my-custom-agent.ts` and modify it for your needs
+2. **Test your agent**: Run `savant-code` without `--agent` so local `.agents` load, then invoke your agent from a prompt
+3. **Publish your agent**: Run `savant-code publish your-agent-name`
+
+## Need Help?
+
+- For examples, check the `examples/` directory.
+- Join our [Discord community](https://savant-code.com/discord) and ask your questions!
+- Check our [documentation](https://savant-code.com/docs) for more details
+
+# What is SavantCode?
+
+SavantCode is an **open-source AI coding assistant** that edits your codebase through natural language instructions.
+Instead of using one model for everything, it coordinates specialized agents that work together to understand your
+project and make precise changes.
+
+SavantCode beats Claude Code at 61% vs 53% on [our evals](https://github.com/savant0x/savant-code/tree/main/evals)
+across 175+ coding tasks over multiple open-source repos that simulate real-world tasks.
+
+## How SavantCode Works
+
+When you ask SavantCode to "add authentication to my API," it might invoke:
+
+1. A **File Explorer Agent** to scan your codebase to understand the architecture and find relevant files
+2. A **Planner Agent** to plan which files need changes and in what order
+3. An **Editor Agent** to make precise edits
+4. A **Reviewer Agent** to validate changes
+
+This multi-agent approach gives you better context understanding, more accurate edits, and fewer errors compared to
+single-model tools.
+
+## Context Window Management
+
+### Why Agent Workflows?
+
+Modern software projects are complex ecosystems with thousands of files, multiple frameworks, intricate dependencies,
+and domain-specific requirements. A single AI agent trying to understand and modify such systems faces fundamental
+limitations—not just in knowledge, but in the sheer volume of information it can process at once.
+
+### The Solution: Focused Context Windows
+
+Agent workflows elegantly solve this by breaking large tasks into focused sub-problems. When working with large
+codebases (100k+ lines), each specialist agent receives only the narrow context it needs—a security agent sees only auth
+code, not UI components—keeping the context for each agent manageable while ensuring comprehensive coverage.
+
+### Why Not Just Mimic Human Roles?
+
+This is about efficient AI context management, not recreating a human department. Simply creating a "frontend-developer"
+agent misses the point. AI agents don't have human constraints like context-switching or meetings. Their power comes
+from hyper-specialization, allowing them to process a narrow domain more deeply than a human could, then coordinating
+seamlessly with other specialists.
+
+## Agent workflows in action
+
+Here's an example of a `git-committer` agent that creates good commit messages:
+
+```typescript
+export default {
+  id: 'git-committer',
+  displayName: 'Git Committer',
+  model: 'openai/gpt-5-nano',
+  toolNames: ['read_files', 'run_terminal_command', 'end_turn'],
+
+  instructionsPrompt:
+    'You create meaningful git commits by analyzing changes, reading relevant files for context, and crafting clear commit messages that explain the "why" behind changes.',
+
+  async *handleSteps() {
+    // Analyze what changed
+    yield { tool: 'run_terminal_command', command: 'git diff' }
+    yield { tool: 'run_terminal_command', command: 'git log --oneline -5' }
+
+    // Stage files and create commit with good message
+    yield 'STEP_ALL'
+  },
+}
+```
+
+This agent systematically analyzes changes, reads relevant files for context, then creates commits with clear,
+meaningful messages that explain the "why" behind changes.
+
+# Agent Development Guide
+
+This guide covers everything you need to know about building custom SavantCode agents.
+
+## Agent Structure
+
+Each agent is a TypeScript file that exports an `AgentDefinition` object:
+
+```typescript
+export default {
+  id: 'my-agent', // Unique identifier (lowercase, hyphens only)
+  displayName: 'My Agent', // Human-readable name
+  model: 'claude-3-5-sonnet', // AI model to use
+  toolNames: ['read_files', 'write_file'], // Available tools
+  instructionsPrompt: 'You are...', // Agent behavior instructions
+  spawnerPrompt: 'Use this agent when...', // When others should spawn this
+  spawnableAgents: ['helper-agent'], // Agents this can spawn
+
+  // Optional: Programmatic control
+  async *handleSteps() {
+    yield { tool: 'read_files', paths: ['src/config.ts'] }
+    yield 'STEP' // Let AI process and respond
+  },
+}
+```
+
+## Core Properties
+
+### Required Fields
+
+- **`id`**: Unique identifier using lowercase letters and hyphens only
+- **`displayName`**: Human-readable name shown in UI
+- **`model`**: AI model from OpenRouter (see [available models](https://openrouter.ai/models))
+- **`instructionsPrompt`**: Detailed instructions defining the agent's role and behavior
+
+### Optional Fields
+
+- **`toolNames`**: Array of tools the agent can use (defaults to common tools)
+- **`spawnerPrompt`**: Instructions for when other agents should spawn this one
+- **`spawnableAgents`**: Array of agent names this agent can spawn
+- **`handleSteps`**: Generator function for programmatic control
+
+## Available Tools
+
+### File Operations
+
+- **`read_files`**: Read file contents
+- **`write_file`**: Create or modify entire files
+- **`str_replace`**: Make targeted string replacements
+- **`code_search`**: Search for patterns across the codebase
+
+### Execution
+
+- **`run_terminal_command`**: Execute shell commands
+- **`spawn_agents`**: Delegate tasks to other agents
+- **`end_turn`**: Finish the agent's response
+
+### Web & Research
+
+- **`web_search`**: Search the internet for information
+- **`read_url`**: Fetch a URL and extract readable page text
+- **`read_docs`**: Read technical documentation
+- **`browser_logs`**: Navigate and inspect web pages
+
+See `types/tools.ts` for detailed parameter information.
+
+## Programmatic Control
+
+Use the `handleSteps` generator function to mix AI reasoning with programmatic logic:
+
+```typescript
+async *handleSteps() {
+  // Execute a tool
+  yield { tool: 'read_files', paths: ['package.json'] }
+
+  // Let AI process results and respond
+  yield 'STEP'
+
+  // Conditional logic
+  if (needsMoreAnalysis) {
+    yield { tool: 'spawn_agents', agents: ['deep-analyzer'] }
+    yield 'STEP_ALL' // Wait for spawned agents to complete
+  }
+
+  // Final AI response
+  yield 'STEP'
+}
+```
+
+### Control Commands
+
+- **`'STEP'`**: Let AI process and respond once
+- **`'STEP_ALL'`**: Let AI continue until completion
+- **Tool calls**: `{ tool: 'tool_name', ...params }`
+
+## Model Selection
+
+Choose models based on your agent's needs:
+
+- **`anthropic/claude-opus-4.7`**: Best general-purpose capabilities and code generation
+- **`openai/gpt-5.2`**: Best at complex reasoning and planning
+- **`google/gemini-3.1-flash-lite`**: Fast and cost-effective for simple or medium-complexity tasks
+
+**Any model on OpenRouter**: Unlike Claude Code which locks you into Anthropic's models, SavantCode supports any model
+available on [OpenRouter](https://openrouter.ai/models) - from Claude and GPT to specialized models like Qwen, DeepSeek,
+and others. Switch models for different tasks or use the latest releases without waiting for platform updates.
+
+See [OpenRouter](https://openrouter.ai/models) for all available models and pricing.
+
+## Agent Coordination
+
+Agents can spawn other agents to create sophisticated workflows:
+
+```typescript
+// Parent agent spawns specialists
+async *handleSteps() {
+  yield { tool: 'spawn_agents', agents: [
+    'security-scanner',
+    'performance-analyzer',
+    'code-reviewer'
+  ]}
+  yield 'STEP_ALL' // Wait for all to complete
+
+  // Synthesize results
+  yield 'STEP'
+}
+```
+
+**Reuse any published agent**: Compose existing [published agents](https://www.savant-code.com/store) to get a leg up.
+SavantCode agents are the new MCP!
+
+## Best Practices
+
+### Instructions
+
+- Be specific about the agent's role and expertise
+- Include examples of good outputs
+- Specify when the agent should ask for clarification
+- Define the agent's limitations
+
+### Tool Usage
+
+- Start with file exploration tools (`read_files`, `code_search`)
+- Use `str_replace` for targeted edits, `write_file` for major changes
+- Always use `end_turn` to finish responses cleanly
+
+### Error Handling
+
+- Include error checking in programmatic flows
+- Provide fallback strategies for failed operations
+- Log important decisions for debugging
+
+### Performance
+
+- Choose appropriate models for the task complexity
+- Minimize unnecessary tool calls
+- Use spawnable agents for parallel processing
+
+## Testing Your Agent
+
+1. **Local Testing**: Run `savant-code` without `--agent` so local `.agents` load, then invoke your agent from a prompt
+2. **Debug Mode**: Add logging to your `handleSteps` function
+3. **Unit Testing**: Test individual functions in isolation
+4. **Integration Testing**: Test agent coordination workflows
+
+## Publishing & Sharing
+
+1. **Validate**: Ensure your agent works across different codebases
+2. **Document**: Include clear usage instructions
+3. **Publish**: `savant-code publish your-agent-name`
+4. **Maintain**: Update as models and tools evolve
+
+## Advanced Patterns
+
+### Conditional Workflows
+
+```typescript
+async *handleSteps() {
+  const config = yield { tool: 'read_files', paths: ['config.json'] }
+  yield 'STEP'
+
+  if (config.includes('typescript')) {
+    yield { tool: 'spawn_agents', agents: ['typescript-expert'] }
+  } else {
+    yield { tool: 'spawn_agents', agents: ['javascript-expert'] }
+  }
+  yield 'STEP_ALL'
+}
+```
+
+### Iterative Refinement
+
+```typescript
+async *handleSteps() {
+  for (let attempt = 0; attempt < 3; attempt++) {
+    yield { tool: 'run_terminal_command', command: 'npm test' }
+    yield 'STEP'
+
+    if (allTestsPass) break
+
+    yield { tool: 'spawn_agents', agents: ['test-fixer'] }
+    yield 'STEP_ALL'
+  }
+}
+```
+
+## Why Choose SavantCode for Custom Agents
+
+**Deep customizability**: Create sophisticated agent workflows with TypeScript generators that mix AI generation with
+programmatic control. Define custom agents that spawn subagents, implement conditional logic, and orchestrate complex
+multi-step processes that adapt to your specific use cases.
+
+**Fully customizable SDK**: Build SavantCode's capabilities directly into your applications with a complete TypeScript
+SDK. Create custom tools, integrate with your CI/CD pipeline, build AI-powered development environments, or embed
+intelligent coding assistance into your products.
+
+Learn more about the SDK [here](https://www.npmjs.com/package/@savant-code/sdk).
+
+## Community & Support
+
+- **Discord**: [Join our community](https://savant-code.com/discord) for help and inspiration
+- **Examples**: Study the `examples/` directory for patterns
+- **Documentation**: [savant-code.com/docs](https://savant-code.com/docs) and check `types/` for detailed type information
+- **Issues**: [Report bugs and request features on GitHub](https://github.com/savant0x/savant-code/issues)
+- **Support**: [support@savant-code.com](mailto:support@savant-code.com)
+
+Happy agent building! 🤖

package/common/src/templates/initial-agents-dir/examples/01-basic-diff-reviewer.ts

@@ -0,0 +1,17 @@
+import type { AgentDefinition } from '../types/agent-definition'
+
+const definition: AgentDefinition = {
+  id: 'basic-diff-reviewer',
+  displayName: 'Basic Diff Reviewer',
+  model: 'anthropic/claude-4-sonnet-20250522',
+  toolNames: ['read_files', 'run_terminal_command'],
+
+  spawnerPrompt: 'Spawn when you need to review code changes in the git diff',
+
+  instructionsPrompt: `Execute the following steps:
+1. Run git diff
+2. Read the files that have changed
+3. Review the changes and suggest improvements`,
+}
+
+export default definition

package/common/src/templates/initial-agents-dir/examples/02-intermediate-git-committer.ts

@@ -0,0 +1,78 @@
+import type {
+  AgentDefinition,
+  AgentStepContext,
+  ToolCall,
+} from '../types/agent-definition'
+
+const definition: AgentDefinition = {
+  id: 'git-committer',
+  displayName: 'Intermediate Git Committer',
+  model: 'anthropic/claude-4-sonnet-20250522',
+  toolNames: ['read_files', 'run_terminal_command', 'add_message', 'end_turn'],
+
+  inputSchema: {
+    prompt: {
+      type: 'string',
+      description: 'What changes to commit',
+    },
+  },
+
+  spawnerPrompt:
+    'Spawn when you need to commit code changes to git with an appropriate commit message',
+
+  systemPrompt:
+    'You are an expert software developer. Your job is to create a git commit with a really good commit message.',
+
+  instructionsPrompt:
+    'Follow the steps to create a good commit: analyze changes with git diff and git log, read relevant files for context, stage appropriate files, analyze changes, and create a commit with proper formatting.',
+
+  handleSteps: function* ({ agentState, prompt, params }: AgentStepContext) {
+    // Step 1: Run git diff and git log to analyze changes.
+    yield {
+      toolName: 'run_terminal_command',
+      input: {
+        command: 'git diff',
+        process_type: 'SYNC',
+        timeout_seconds: 30,
+      },
+    } satisfies ToolCall
+
+    yield {
+      toolName: 'run_terminal_command',
+      input: {
+        command: 'git log --oneline -10',
+        process_type: 'SYNC',
+        timeout_seconds: 30,
+      },
+    } satisfies ToolCall
+
+    // Step 2: Put words in AI's mouth so it will read files next.
+    yield {
+      toolName: 'add_message',
+      input: {
+        role: 'assistant',
+        content:
+          "I've analyzed the git diff and recent commit history. Now I'll read any relevant files to better understand the context of these changes.",
+      },
+      includeToolCall: false,
+    } satisfies ToolCall
+
+    // Step 3: Let AI generate a step to decide which files to read.
+    yield 'STEP'
+
+    // Step 4: Put words in AI's mouth to analyze the changes and create a commit.
+    yield {
+      toolName: 'add_message',
+      input: {
+        role: 'assistant',
+        content:
+          "Now I'll analyze the changes and create a commit with a good commit message.",
+      },
+      includeToolCall: false,
+    } satisfies ToolCall
+
+    yield 'STEP_ALL'
+  },
+}
+
+export default definition

package/common/src/templates/initial-agents-dir/examples/03-advanced-file-explorer.ts

@@ -0,0 +1,76 @@
+import type { AgentDefinition, ToolCall } from '../types/agent-definition'
+
+const definition: AgentDefinition = {
+  id: 'advanced-file-explorer',
+  displayName: 'Dora the File Explorer',
+  model: 'openai/gpt-5.1',
+
+  spawnerPrompt:
+    'Spawns multiple file picker agents in parallel to comprehensively explore the codebase from different perspectives',
+
+  includeMessageHistory: false,
+  toolNames: ['spawn_agents', 'set_output'],
+  spawnableAgents: [`savant-code/scout@0.0.1`],
+
+  inputSchema: {
+    prompt: {
+      description: 'What you need to accomplish by exploring the codebase',
+      type: 'string',
+    },
+    params: {
+      type: 'object',
+      properties: {
+        prompts: {
+          description:
+            'List of 1-4 different parts of the codebase that could be useful to explore',
+          type: 'array',
+          items: {
+            type: 'string',
+          },
+        },
+      },
+      required: ['prompts'],
+      additionalProperties: false,
+    },
+  },
+  outputMode: 'structured_output',
+  outputSchema: {
+    type: 'object',
+    properties: {
+      results: {
+        type: 'string',
+        description: 'The results of the file exploration',
+      },
+    },
+    required: ['results'],
+    additionalProperties: false,
+  },
+
+  handleSteps: function* ({ prompt, params }) {
+    const rawPrompts = params?.prompts
+    const prompts: string[] = Array.isArray(rawPrompts)
+      ? rawPrompts.filter((item): item is string => typeof item === 'string')
+      : []
+    const filePickerPrompts = prompts.map(
+        (focusPrompt) =>
+          `Based on the overall goal "${prompt}", find files related to this specific area: ${focusPrompt}`,
+      ),
+      { toolResult: spawnResult } = yield {
+        toolName: 'spawn_agents',
+        input: {
+          agents: filePickerPrompts.map((promptText) => ({
+            agent_type: 'savant-code/scout@0.0.1',
+            prompt: promptText,
+          })),
+        },
+      } satisfies ToolCall
+    yield {
+      toolName: 'set_output',
+      input: {
+        results: spawnResult,
+      },
+    } satisfies ToolCall
+  },
+}
+
+export default definition

package/common/src/templates/initial-agents-dir/my-custom-agent.ts

@@ -0,0 +1,40 @@
+/*
+ *  EDIT ME to create your own agent!
+ *
+ *  Run your agent with:
+ *  > savant-code
+ *  Inside savant-code:
+ *  > @my-custom-agent please review my recent changes
+ *
+ *  Finally, you can publish your agent with:
+ *  > savant-code publish my-custom-agent
+ *  Then users from around the world can run it!
+ */
+
+import type { AgentDefinition } from './types/agent-definition'
+
+const definition: AgentDefinition = {
+  id: 'my-custom-agent',
+  displayName: 'My Custom Agent',
+
+  model: 'x-ai/grok-4-fast',
+  spawnableAgents: ['savant-code/file-explorer@0.0.6'],
+
+  // Check out .agents/types/tools.ts for more information on the tools you can include.
+  toolNames: ['run_terminal_command', 'read_files', 'spawn_agents'],
+
+  spawnerPrompt: 'Spawn when you need to review code changes in the git diff',
+
+  instructionsPrompt: `Review the code changes and suggest improvements.
+Execute the following steps:
+1. Run git diff
+2. Spawn a file explorer to find all relevant files
+3. Read any relevant files
+4. Review the changes and suggest improvements`,
+
+  // See also:
+  // - types/agent-definition.ts file for more fields you can add
+  // - the examples directory for more ideas!
+}
+
+export default definition

package/common/src/templates/initial-agents-dir/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "savant-code-agents",
+  "version": "0.0.1",
+  "description": "This directory contains your custom Savant-Code agents. Each agent is a TypeScript file that defines an AI agent with specific capabilities and behavior.",
+  "license": "Apache-2.0"
+}

package/common/src/templates/initial-agents-dir/skills/README.md

@@ -0,0 +1,66 @@
+# Skills
+
+Skills are reusable instruction sets that agents can load on-demand via the `skill` tool.
+
+## Creating a Skill
+
+1. Create a directory with your skill name (lowercase alphanumeric with hyphens):
+   ```text
+   .agents/skills/my-skill/
+   ```
+
+2. Create a `SKILL.md` file with YAML frontmatter:
+   ```markdown
+   ---
+   name: my-skill
+   description: A short description of what this skill does
+   license: MIT
+   metadata:
+     category: development
+   ---
+
+   # My Skill
+
+   Instructions and content for the skill...
+   ```
+
+## Frontmatter Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Skill name (1-64 chars, lowercase alphanumeric with hyphens, must match directory name) |
+| `description` | Yes | Short description (1-1024 chars) used for agent discovery |
+| `license` | No | License identifier (e.g., "MIT", "Apache-2.0") |
+| `metadata` | No | Key-value pairs for additional categorization |
+
+## Name Validation
+
+Skill names must:
+
+- Be 1-64 characters long
+- Use only lowercase letters, numbers, and hyphens
+- Not start or end with a hyphen
+- Not contain consecutive hyphens
+- Match the directory name exactly
+
+Valid examples: `git-release`, `api-design`, `review2`
+Invalid examples: `Git-Release`, `my--skill`, `-skill`, `skill-`
+
+## Discovery Locations
+
+Skills are discovered from these locations (in order of precedence):
+
+1. `~/.agents/skills/` (global, lowest priority)
+2. `.agents/skills/` (project, highest priority)
+
+Project skills override global skills with the same name.
+
+## How Agents Use Skills
+
+Agents see available skills listed in the `skill` tool description. When an agent needs a skill's instructions, it calls:
+
+```typescript
+skill({ name: "my-skill" })
+```
+
+The full SKILL.md content is then returned to the agent.

package/common/src/templates/initial-agents-dir/skills/example-skill/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: example-skill
+description: An example skill demonstrating the SKILL.md format
+license: MIT
+metadata:
+  category: examples
+  audience: developers
+---
+
+# Example Skill
+
+This is an example skill that demonstrates the SKILL.md format.
+
+## When to use this skill
+
+Use this skill when you need an example of how skills work.
+
+## Instructions
+
+1. Skills are loaded on-demand via the `skill` tool
+2. The agent sees available skills listed in the tool description
+3. When needed, the agent calls `skill({ name: "example-skill" })` to load the full content
+4. The skill content is then available in the conversation context
+
+## Notes
+
+- Skills should have clear, specific descriptions
+- The name must be lowercase alphanumeric with hyphens
+- The name must match the directory name