Coding Agent

The coding agent is a specialist personality with focused file-editing, shell, and git tools. You can reach it from any channel — “ask the coding agent to…”, or just start talking about code and the router will pick it automatically.

What It Can Do

• Read, edit, and create files in a workspace
• Run shell commands inside a sandbox
• Use git (status, diff, commit, log, branch, PR create)
• Search file contents and filenames
• Follow project instructions from BUTLER.md

Tools

Tool	What it does
file.read	Read a file with line numbers
file.write	Create a new file
file.edit	Replace a string (exact match)
file.list	List a directory, optionally by glob pattern
file.search	Recursive content search
shell.exec	Run a shell command in the workspace sandbox
git.status	Repository status
git.diff	Staged and unstaged changes
git.commit	Stage files and create a commit
git.log	Recent commits
git.branch	Create, list, or switch branches
git.pr_create	Create a pull request using the GitHub CLI

All tools are capability-gated — even if the agent tries to call one, the capability engine checks whether the current channel and session have the corresponding grant.

Workspace Sandbox

shell.exec runs inside a workspace sandbox. On Linux this uses unshare namespaces; on macOS it uses sandbox-exec. Commands cannot escape the workspace unless the sandbox is in allow-list mode and the target path is explicitly allowed:

configurations:
  sandbox:
    mode: workspace-only    # off | workspace-only | allow-list
    allow_paths:
      - /home/me/projects
      - /tmp

BUTLER.md — Project Instructions

Like CLAUDE.md in Claude Code, AI Butler reads a BUTLER.md file from the current workspace root. Use it to give the agent project-specific context: test commands, style rules, architecture notes, gotchas.

BUTLER.md

This is a Go 1.26 project. Run tests with `go test -race ./...`.
Use `gofumpt` for formatting. Never use CGO — we compile with `CGO_ENABLED=0`.

See BUTLER.md configuration for the full format.

Hooks

Hooks let you run shell commands before or after tool calls — useful for auto-formatting, running tests, or blocking dangerous edits:

configurations:
  hooks:
    post_tool_use:
      - command: "gofumpt -w ."
        tools: ["file.edit", "file.write"]

See Hooks for the full reference.

Cross-Channel Coding

Because channels share state, you can start a coding session on the terminal REPL and continue it on Telegram — the agent remembers the workspace, the current branch, and the in-progress work.

You (terminal):  run the tests and show me what's failing
Butler: TestAuth_RBAC_DeniesUnauthorized failed at auth_test.go:142

...later, on Telegram...

You: fix the RBAC test
Butler: Working on auth_test.go:142 — the assertion expected 403 but got 401.
        I'll update the middleware to return 403 for authenticated-but-unauthorized
        requests.

Real conversations — the coding agent at work

Three live scenarios against a running AI Butler instance exploring its own codebase. Every screenshot is real tool output.

1. Read a file and review it

Sometimes you want a sanity check on a config file or a dependency manifest. Ask naturally:

You: Read the file at /tmp/aibutler-demo/example-project/go.mod and tell me:

• Which Go version does this project require?
• How many direct dependencies does it have?
• Which dependencies are ‘indirect’ vs ‘direct’?
• Flag anything that looks unusual (pinned versions, replace directives, etc.)

Use your file read tool to actually look at the file, don’t guess.

The agent calls file.read on go.mod, parses the module manifest, and produces a review with 5 flagged observations — including a real typo it caught on the spot:

Notice what the agent did beyond answering the literal question: it spotted a Go version typo, flagged 3 unpinned dependencies with commit hashes, noted the absence of replace directives as a good sign, and explained what each unusual dependency provides. This is the kind of review a human engineer would do when skimming a manifest — except you got it in 15 seconds without leaving the chat.

2. Search the codebase for a pattern

When you’re debugging or trying to understand existing architecture, grep is your friend. Butler wraps it in natural language:

You: I’m trying to understand how the capability engine is wired into the agent loop. Search the /tmp/aibutler-demo/example-project/internal/agent directory for the string capability.WithCaps and show me every occurrence with file paths and surrounding context. Then explain what each usage is doing in one sentence.

The agent calls file.search, finds every match, and draws you an ASCII flow diagram of how capabilities propagate through the dispatch chain:

This is genuinely useful code review. The agent didn’t just grep — it connected the dots between the call sites, inferred the architectural pattern (context-based propagation vs function arguments), and explained why that pattern was chosen. If you’re reading an unfamiliar codebase trying to understand the permission model, this is the kind of answer that saves an hour of tracing calls by hand.

3. Map a whole directory

For a new-to-the-repo question, it’s often easier to ask for the big-picture structure:

You: Give me a high-level map of the /tmp/aibutler-demo/example-project/internal directory. List the top-level subdirectories and for each one describe in one sentence what it does based on the folder name and any obvious clues. I want to understand the project’s package organization quickly.

The agent calls file.list on internal/, walks the subdirectories, and returns a categorized package index with ~55 packages grouped by concern (core runtime, channel frontends, skill/tool integrations, protocol infrastructure, utilities):

The closing summary — “The architecture is cleanly layered: a core agent runtime, pluggable channel frontends, skill/tool integrations, a security stack, and protocol infrastructure (MCP/A2A) — which maps well to your interests in agent interoperability” — demonstrates something important: the agent is drawing on your memory (it knows you’re interested in A2A + MCP from previous conversations) to tailor its explanation. That’s the full stack working together — file tools + memory graph + natural language — and it’s the reason AI Butler feels different from a plain coding CLI.

What these demos prove

What you saw	Why it matters
file.read with structured review	Not just “cat the file” — the agent produces actionable observations (typos, anti-patterns, unusual deps)
file.search + architectural diagram	Code archaeology becomes a 15-second conversation instead of a 20-minute trace
file.list + memory-aware summary	The agent tailors its explanation to what it already knows about you
Every tool call ran inside the workspace sandbox	No way to accidentally read outside the allowed paths
Every call was capability-gated + audit-logged	The same security posture that protects your smart home protects your codebase