Can Tolaria Be Used for Automated Refactoring?

Yes. Tolaria enables automated refactoring through its Model-Context-Protocol (MCP) server, which exposes Git-tracked vault operations as tool calls that AI agents can invoke to read, edit, rename, and commit markdown notes programmatically.

Tolaria is a Git-first markdown vault application architected specifically for automated manipulation. According to the refactoringhq/tolaria source code, every note exists as a plain markdown file in a Git repository, while an integrated MCP server provides 14 vault-operation tools accessible via stdio and WebSocket. This design creates a complete pipeline where AI agents can perform large-scale refactors that remain fully auditable and reversible through standard Git workflows.

The MCP Server Architecture and Git-First Design

The foundation of Tolaria’s automation capability is its MCP (Model-Context-Protocol) server, defined in mcp-server/ws-bridge.js and documented in docs/adr/0011-mcp-server-for-ai-integration.md. This server exposes vault operations—including search, read, edit, rename, and commit—as discrete tools that AI models can invoke through a standardized interface.

Because Tolaria uses a file-first, Git-first vault architecture, every automated edit is automatically versioned. When an AI agent calls edit_note or rename_note, the underlying operation modifies a standard markdown file within a Git repository. This ensures that every automated refactor generates a diff that can be inspected, rolled back, or pushed to a remote repository, with PostHog telemetry logging all actions for audit trails.

Permission Modes: Vault Safe vs. Power User

Tolaria implements permission modes that act as safety gates during automated refactoring. When an AI agent is invoked via the Agent Panel or programmatically, Tolaria builds a system prompt using src/utils/ai-agent.ts that instructs the model on available tools and restrictions.

• Vault Safe: The default mode for automated refactoring. This disables shell command execution and restricts the agent to MCP tool calls only, ensuring refactors remain limited to note content and file operations.
• Power User: An elevated mode that can be enabled when automation requires shell access or system-level operations outside the vault.

These modes are enforced through the system prompt configuration, allowing you to run aggressive refactoring scripts without risking arbitrary code execution on the host system.

Implementing Automated Refactoring Workflows

The src/utils package provides concrete utilities for implementing refactoring logic across multiple integration points.

Building System Prompts with buildAgentSystemPrompt

To initiate an AI-driven refactor, first construct a system prompt that defines the operational constraints:

// src/utils/ai-agent.ts
import { buildAgentSystemPrompt } from './ai-agent';

const prompt = buildAgentSystemPrompt({
  permissionMode: 'safe',  // disallow shell, only MCP tools
  agent: 'claude',         // the chosen AI model
});

This prompt object is then sent to the LLM, informing it that it may use MCP tools but must respect the specified safety constraints.

Executing Individual Operations

For targeted refactors like renaming a note, you can call MCP tools directly from CLI scripts or automation jobs:

// scripts/rename-note.ts
// Assumes the MCP server is already running (spawned by Tolaria)
import { rename_note } from '@mcp/client';

async function refactorNote(oldPath: string, newPath: string) {
  await rename_note({ from: oldPath, to: newPath });
  console.log(`✅ Renamed ${oldPath} → ${newPath}`);
}

refactorNote('notes/old-name.md', 'notes/new-name.md');

Streaming Bulk Refactors via streamAiAgent

For complex operations that require iterative reasoning, use the streaming helper to process tool calls as the model generates them:

// src/utils/streamAiAgent.ts
import { streamAiAgent } from './streamAiAgent';

const prompt = buildAgentSystemPrompt({
  permissionMode: 'power_user',
  agent: 'claude',
});

streamAiAgent(prompt, async (tool, args) => {
  // The LLM decides to apply a refactor across multiple notes
  if (tool === 'edit_note') {
    const { path, newContent } = args;
    await edit_note({ path, content: newContent });
  }
});

This pattern allows the AI to perform multi-step refactors—such as updating internal links or standardizing frontmatter—while Tolaria handles the execution and error handling for each tool invocation.

Automating Commits with generateAutomaticCommitMessage

After automated edits complete, generate semantic commit messages using the built-in helper:

import { generateAutomaticCommitMessage } from './automaticCommitMessage';

async function commitRefactor() {
  const msg = await generateAutomaticCommitMessage({
    changedFiles: ['notes/feature-x.md', 'notes/feature-y.md'],
    description: 'Apply new type naming convention',
  });
  await gitCommit({ message: msg });
}

This utility ensures that automated refactoring sessions produce human-readable Git history, integrating with CodeScene health checks to validate the refactor impact before finalizing.

Triggering Refactors from Multiple Interfaces

Tolaria exposes the same MCP-backed refactoring engine through three distinct entry points:

• UI Components: The Command Palette and Agent Panel provide graphical access to AI agents, triggering the same streamAiAgent.ts utilities used by scripts.
• CLI Scripts: Node.js or TypeScript files can import from @mcp/client to execute refactors against a running Tolaria instance, ideal for CI/CD pipelines.
• Programmatic Access: Directly import helpers from src/utils/ai-agent.ts, src/utils/streamAiAgent.ts, or src/utils/automaticCommitMessage.ts to build custom automation workflows that bypass the UI entirely.

All three paths invoke identical validation, safety-gates, and health checks, ensuring consistency whether the refactor is triggered by a human clicking a button or an unsupervised cron job.

Summary

• Tolaria’s MCP server exposes 14 vault-operation tools via mcp-server/ws-bridge.js, enabling standardized AI agent integration over stdio and WebSocket.
• The Vault Safe permission mode restricts automated agents to MCP tool calls only, preventing shell command execution during refactors.
• Every automated change is automatically tracked in Git due to the file-first architecture, with src/utils/automaticCommitMessage.ts providing semantic commit message generation.
• Utilities in src/utils/ai-agent.ts and src/utils/streamAiAgent.ts provide ready-made integration points for building custom refactoring pipelines.

Frequently Asked Questions

What prevents an AI agent from making dangerous system changes during automated refactoring?

Tolaria enforces the Vault Safe permission mode by default when generating system prompts in src/utils/ai-agent.ts. This mode explicitly disables shell command execution and restricts the agent to vault-specific MCP tools like edit_note and rename_note. Only when explicitly switched to Power User mode can an agent access system-level operations.

How does Tolaria track changes made by automated refactoring scripts?

Because Tolaria uses a Git-first vault architecture where every note is a plain markdown file, all changes made via MCP tool calls are automatically captured as Git working directory modifications. The src/utils/automaticCommitMessage.ts utility can then generate descriptive commit messages, allowing you to audit, revert, or branch automated refactors using standard Git workflows.

Can I use Tolaria for automated refactoring without the graphical interface?

Yes. While the Agent Panel provides a UI for triggering refactors, you can also execute automation via CLI scripts that import from @mcp/client or by directly calling the helper functions in src/utils/streamAiAgent.ts from your own TypeScript or Node.js applications.

Does Tolaria support bulk refactoring operations across multiple notes?

Yes. The streamAiAgent utility in src/utils/streamAiAgent.ts supports streaming responses where an AI agent can issue multiple tool calls—such as edit_note for each file in a directory—within a single session. This enables bulk operations like renaming concepts across an entire vault or standardizing metadata formats, all while respecting the configured permission modes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}