# Can Tolaria Be Used for Automated Refactoring?

> Yes, Tolaria powers automated refactoring by exposing Git-tracked vault operations as tool calls for AI agents to programmatically read, edit, rename, and commit markdown notes via its MCP server.

- Repository: [Refactoring/tolaria](https://github.com/refactoringhq/tolaria)
- Tags: getting-started
- Published: 2026-05-04

---

**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`](https://github.com/refactoringhq/tolaria/blob/main/mcp-server/ws-bridge.js) and documented in [`docs/adr/0011-mcp-server-for-ai-integration.md`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/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:

```typescript
// 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:

```typescript
// 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:

```typescript
// 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:

```typescript
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`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/src/utils/ai-agent.ts), [`src/utils/streamAiAgent.ts`](https://github.com/refactoringhq/tolaria/blob/main/src/utils/streamAiAgent.ts), or [`src/utils/automaticCommitMessage.ts`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/src/utils/automaticCommitMessage.ts) providing semantic commit message generation.
- Utilities in [`src/utils/ai-agent.ts`](https://github.com/refactoringhq/tolaria/blob/main/src/utils/ai-agent.ts) and [`src/utils/streamAiAgent.ts`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/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.