Skip to main content

Workflows and Extension

Helix is designed to handle real engineering work, which means it needs structured workflows for code changes, a way to customize agent behavior per project, and clean extension points so you can teach it new capabilities without modifying the core system.

This page covers four pillars: the Git worktree workflow that isolates code changes, the Agent Profile system that controls how agents behave, the Skills system that injects domain knowledge, and custom MCP server configuration for extending the tool set.

Git Worktree Workflow​

When an agent needs to modify code, Helix creates an isolated Git worktree so changes happen on a separate branch. This protects your working tree from half-finished edits and lets multiple sub agents modify code concurrently without stepping on each other.

How It Works​

  1. Binding creation — The agent calls create_worktree_binding with a project directory and task description
  2. Branch setup — Helix resolves the Git root, takes the current branch as base, and creates a new branch named aiagent/{sessionID}/{task-description}-{hash}
  3. Worktree creation — A separate working directory is created under the Helix data directory, checked out on the new branch
  4. Work execution — The agent (or sub agent) reads, edits, and commits files in the worktree without touching the original working directory
  5. Merge back — When the task completes, Helix commits any remaining changes, switches to the base branch, pulls latest, performs a --no-ff merge, and cleans up the worktree and temporary branch

Why This Matters​

  • Safety — Your main working tree is never modified directly. If the agent's changes are not what you wanted, you can inspect the branch before merging.
  • Parallelism — Multiple sub agents can each have their own worktree and branch, modifying different parts of the codebase simultaneously without merge conflicts during execution.
  • Code review — The system prompt instructs agents to run start_code_review before merging, creating a built-in quality gate for AI-generated changes.
  • Clean history — The --no-ff merge preserves a clear record of what the agent changed and when.

Example Flow​

User: "Refactor the authentication module and update its tests"

Agent thinking:
  → Create worktree binding for the auth module
  → Spawn sub agent A: refactor auth module (in worktree A)
  → Spawn sub agent B: update auth tests (in worktree B)
  → Both work concurrently on isolated branches
  → Each runs code review before completing
  → Changes merge back to main branch sequentially
tip

You do not need to create worktrees manually. The agent decides when isolation is needed based on the task. For read-only tasks like code review or architecture analysis, no worktree is created.

Agent Profiles​

Agent Profiles let you create reusable configurations that control how agents behave. Each profile defines the model, available tools, thinking behavior, and operational parameters. You can create profiles tuned for different tasks: a fast reviewer, a thorough architect, a cost-conscious daily assistant.

Profile Configuration​

Profiles are stored as YAML files in ~/.aiagent/agent/{id}.yaml. Each profile can configure:

FieldWhat it controls
ModelWhich LLM to use, specified as providerId:modelId
MCP ServersWhich MCP servers the agent can access (limits the tool set)
Thinking ModeWhether extended thinking is enabled and the token budget
LanguageAgent's response language (e.g. zh, en)
TimeoutMaximum session duration (supports sessions over 5 hours)
Cache and CompactionStrategy for context caching and conversation compaction

How Profiles Connect to Workspaces​

Profiles are bound to workspaces. When you create a new chat session in a workspace, the workspace's profile configuration is applied automatically. This means you can set up:

  • A code workspace with Claude + full Serena LSP + thinking enabled for deep engineering work
  • A review workspace with DeepSeek + read-only tools for cost-effective code review
  • An ops workspace with Remote SSH + Shell tools for server management tasks

Each workspace keeps its own profile configuration, so switching between projects also switches the agent's behavior and capabilities.

Restricting Tools per Profile​

One of the most useful profile features is MCP server filtering. By listing only specific MCP servers in a profile, you can create agents that are focused and safe:

# Example: read-only review agent
mcp_servers:
  - builtin_serena  # Code intelligence (can be set to planning mode)
  - builtin_skills  # Access to review skills

This profile cannot execute shell commands, modify files outside Serena's control, or access remote servers. It is limited to reading, analyzing, and reporting.

Skills System​

Skills are Helix's mechanism for injecting domain-specific knowledge and workflows into agents. A skill is a Markdown file with structured prompts that the agent loads on demand when it encounters a task that matches the skill's description.

How Skills Work​

  1. Discovery — When a session starts, Helix reads the metadata (name and description) of all available skills and includes them in the system prompt
  2. Matching — The agent sees the skill list and decides whether any skill is relevant to the current task
  3. Loading — The agent calls read_skill(name) to load the full skill content into the conversation
  4. Execution — The skill's instructions guide the agent through a specific workflow or set of conventions

This two-stage approach keeps the system prompt compact. Instead of loading every possible instruction upfront, agents pull in what they need when they need it.

Skill File Format​

Every skill is a directory containing a SKILL.md file. The file uses YAML frontmatter for metadata and Markdown for the actual instructions:

---
name: commit
description: Smart commit assistant that checks incremental code changes,
  filters large files and binary artifacts, and safely executes git commit.
version: "1.0"
author: your-name
tags: [git, commit, safety]
---

# Smart Commit Assistant

You are a smart Git commit assistant that helps users safely commit code changes.
Before executing `git add`, you check whether new files contain large files
or binary artifacts, and stop immediately if problems are found.

## Workflow

### Step 1: Check current Git status

(detailed instructions follow...)

Built-in Skills​

Helix ships with three built-in skills:

SkillPurpose
commitSmart commit assistant — checks for large files and binary artifacts before committing, generates clear commit messages
serenaSerena LSP coding assistant — provides detailed instructions for using symbol-level code analysis and editing tools
code-reviewerCode review assistant — analyzes code quality, security issues, and best practices across local repos or remote merge requests

Creating Your Own Skills​

Custom skills go in ~/.aiagent/skills/. Create a directory with a SKILL.md file:

~/.aiagent/skills/
  my-deploy-skill/
    SKILL.md          # Required: skill definition
    checklist.md      # Optional: supplementary resource
    config-template/  # Optional: template files

The agent can access supplementary files through read_skill_file(skill, file) and list what is available with list_skill_files(skill).

Practical skill ideas:

  • Deploy workflow — Step-by-step deployment instructions specific to your infrastructure
  • API conventions — Your team's API design standards and patterns
  • Testing strategy — Project-specific testing approaches and coverage requirements
  • PR review checklist — Custom review criteria for your codebase
  • Incident response — Runbook-style instructions for common production issues
info

If a custom skill has the same name as a built-in skill, the custom version takes priority. This lets you override built-in behavior when needed.

Putting It All Together​

Helix's extension points work together. A typical advanced setup might look like:

  1. Agent Profile defines a Claude model with thinking enabled and a curated set of MCP servers
  2. Workspace binds the profile to a specific project directory
  3. Skills inject your team's conventions for commits, reviews, and deployments
  4. Custom MCP servers add database access and issue tracker integration
  5. Git worktree isolates code changes so the agent can work freely without risk

The agent starts a task, loads relevant skills, uses the available tools, creates worktrees for code changes, runs reviews, and merges results — all within a structured workflow that you configured once and reuse across sessions.

What Comes Next​