Skip to main content
@coder is the engineering suite used by Coder Mode (/coder). It provides actions for reading/searching files, safely applying patches, running commands, and reverting changes.
@coder is a builtin plugin — it comes embedded in the ChatCLI binary and works immediately, without installation. If you need a custom version, simply place the binary in ~/.chatcli/plugins/ and it will take precedence over the builtin. When removed, the builtin returns automatically on the next /plugin reload.

​
Quick Reference

All subcommands and their most commonly used flags at a glance:
SubcommandDescriptionKey Flags
readRead file contents--file (req.), --start, --end, --head, --tail
writeWrite file with backup--file (req.), --content (req.), --append, --encoding
patchApply search/replace or unified diff--file, --search, --replace, --diff, --encoding
multipatchAtomic transaction of multiple search/replace edits across multiple files. All-or-nothing rollback.--edits (req., JSON array)
treeDirectory structure--dir, --glob, --max-entries
searchFull-text search in files--term (req.), --dir, --glob, --max-results, --context
execExecute shell commands--cmd (req.), --command
testRun tests--dir, --pattern, --timeout
git-statusRepository status(no flags)
git-diffPending differences--file, --staged
git-logCommit history--oneline, --limit
git-changedChanged files--staged
git-branchList branches--all
rollbackRestore file from .bak backup--file (req.)
cleanRemove .bak files(no required flags)

​
Argument Formats

@coder accepts two argument formats: JSON and CLI-style. Both are equivalent.

​
Subcommands — Complete Reference

Reads the contents of a file from disk. Supports partial reading by line range and byte limits.

​
Flags

FlagTypeRequiredDefaultDescription
--filestringYes—Path of the file to read
--startintNo—Start line (1-based)
--endintNo—End line (1-based)
--headintNo—First N lines
--tailintNo—Last N lines
--max-bytesintNo200000Maximum byte limit for output
--encodingstringNotextOutput encoding: text or base64

​
Examples

<!-- Read entire file -->
<tool_call name="@coder" args='{"cmd":"read","args":{"file":"README.md"}}'/>

<!-- Read lines 10 to 50 -->
<tool_call name="@coder" args='{"cmd":"read","args":{"file":"main.go","start":10,"end":50}}'/>

<!-- First 20 lines -->
<tool_call name="@coder" args='{"cmd":"read","args":{"file":"config.yaml","head":20}}'/>

<!-- Last 30 lines -->
<tool_call name="@coder" args='{"cmd":"read","args":{"file":"app.log","tail":30}}'/>

<!-- Output in base64 (useful for binaries) -->
<tool_call name="@coder" args='{"cmd":"read","args":{"file":"image.png","encoding":"base64","max-bytes":500000}}'/>
Use --head or --tail to avoid very large outputs. The --max-bytes limit (default 200KB) acts as a safety net even when not explicitly specified.
Writes content to a file. Automatically creates a .bak backup of the existing file before overwriting.

​
Flags

FlagTypeRequiredDefaultDescription
--filestringYes—Path of the file to write
--contentstringYes—Content to write
--encodingstringNotextContent encoding: text or base64
--appendboolNofalseIf true, appends to the file instead of overwriting

​
Examples

<!-- Write new file (text) -->
<tool_call name="@coder" args='{"cmd":"write","args":{"file":"hello.txt","content":"Hello, World!"}}'/>

<!-- Write with base64-encoded content -->
<tool_call name="@coder" args='{"cmd":"write","args":{"file":"data.bin","content":"SGVsbG8gV29ybGQ=","encoding":"base64"}}'/>

<!-- Append to an existing file -->
<tool_call name="@coder" args='{"cmd":"write","args":{"file":"notes.txt","content":"\nNew line appended","append":true}}'/>
Use --encoding base64 for content containing special characters, complex line breaks, or binary data. This avoids escaping issues in JSON.
Applies changes to an existing file. Supports two modes: search/replace (replaces a specific section) and unified diff (applies a patch in diff format).

​
Flags

FlagTypeRequiredDefaultDescription
--filestringConditional—File to patch. Required for search/replace; optional for diff (the diff may contain paths)
--searchstringConditional—Text to find (search/replace mode)
--replacestringConditional—Replacement text (search/replace mode)
--diffstringConditional—Unified diff content (diff mode)
--encodingstringNotextEncoding for --search and --replace: text or base64
--diff-encodingstringNotextEncoding for --diff: text or base64
You must use either search/replace mode (--search + --replace) or diff mode (--diff). Do not combine both.

​
Search/Replace Mode

<!-- Replace text (plain text) -->
<tool_call name="@coder" args='{"cmd":"patch","args":{"file":"main.go","search":"fmt.Println(\"old\")","replace":"fmt.Println(\"new\")"}}'/>

<!-- Replace text (base64 to avoid escaping) -->
<tool_call name="@coder" args='{"cmd":"patch","args":{"file":"main.go","search":"Zm10LlByaW50bG4oIm9sZCIp","replace":"Zm10LlByaW50bG4oIm5ldyIp","encoding":"base64"}}'/>

​
Unified Diff Mode

<!-- Apply diff as text -->
<tool_call name="@coder" args='{"cmd":"patch","args":{"diff":"--- a/main.go\n+++ b/main.go\n@@ -5,3 +5,3 @@\n-old line\n+new line"}}'/>

<!-- Apply diff as base64 -->
<tool_call name="@coder" args='{"cmd":"patch","args":{"diff":"LS0tIGEvbWFpbi5nbw...","diff-encoding":"base64"}}'/>
The base64 mode is strongly recommended for patches, especially when the content contains quotes, backslashes, or multiple lines. This eliminates JSON escaping issues entirely.
Lists the directory structure in tree format. Useful for understanding project organization.

​
Flags

FlagTypeRequiredDefaultDescription
--dirstringNo"."Root directory to list
--globstringNo—Glob pattern to filter files (e.g., "*.go")
--max-entriesintNo2000Maximum number of entries returned

​
Examples

<!-- List current directory -->
<tool_call name="@coder" args='{"cmd":"tree","args":{"dir":"."}}'/>

<!-- List only Go files -->
<tool_call name="@coder" args='{"cmd":"tree","args":{"dir":".","glob":"*.go"}}'/>

<!-- List subdirectory with limit -->
<tool_call name="@coder" args='{"cmd":"tree","args":{"dir":"./internal","max-entries":500}}'/>
Searches for a term across all files in a directory. Returns snippets with surrounding context.

​
Flags

FlagTypeRequiredDefaultDescription
--termstringYes—Search term
--dirstringNo"."Directory to search in
--globstringNo—Glob pattern to filter files (e.g., "*.go", "*.ts")
--max-resultsintNo100Maximum number of results
--contextintNo2Context lines before and after each match

​
Examples

<!-- Simple search -->
<tool_call name="@coder" args='{"cmd":"search","args":{"term":"TODO","dir":"."}}'/>

<!-- Search in Go files with more context -->
<tool_call name="@coder" args='{"cmd":"search","args":{"term":"func main","dir":".","glob":"*.go","context":5}}'/>

<!-- Search with result limit -->
<tool_call name="@coder" args='{"cmd":"search","args":{"term":"error","dir":"./pkg","max-results":20}}'/>
Executes an arbitrary command in the shell. Has built-in security protections against destructive commands.

​
Flags

FlagTypeRequiredDefaultDescription
--cmdstringYes—Command to execute
--commandstringNo—Alias for --cmd

​
Examples

<!-- Execute a simple command -->
<tool_call name="@coder" args='{"cmd":"exec","args":{"cmd":"go build ./..."}}'/>

<!-- List processes -->
<tool_call name="@coder" args='{"cmd":"exec","args":{"cmd":"ps aux | grep myapp"}}'/>

<!-- Using the --command alias -->
<tool_call name="@coder" args='{"cmd":"exec","args":{"command":"ls -la"}}'/>
exec automatically blocks commands considered dangerous, including:
  • rm -rf / and destructive variants
  • dd targeting disk devices
  • Fork bombs (e.g., :(){ :|:& };:)
  • Other recognizably destructive patterns
These blocks exist to protect the system. Use responsibly.
Runs project tests automatically, detecting the framework based on the directory contents.

​
Flags

FlagTypeRequiredDefaultDescription
--dirstringNo"."Directory where to run tests
--patternstringNo—Test file pattern (e.g., "*_test.go")
--timeoutintNo30Timeout in seconds

​
Examples

<!-- Run all tests -->
<tool_call name="@coder" args='{"cmd":"test","args":{"dir":"."}}'/>

<!-- Run tests with specific pattern -->
<tool_call name="@coder" args='{"cmd":"test","args":{"dir":"./pkg","pattern":"*_test.go","timeout":60}}'/>
Shows the Git repository status (modified, staged, untracked files, etc.).No flags required.

​
Examples

<tool_call name="@coder" args='{"cmd":"git-status","args":{}}'/>
Shows the diff of modified files in the repository.

​
Flags

FlagTypeRequiredDefaultDescription
--filestringNo—Filter diff to a specific file
--stagedboolNofalseShow only staged changes (ready for commit)

​
Examples

<!-- Full diff -->
<tool_call name="@coder" args='{"cmd":"git-diff","args":{}}'/>

<!-- Diff for a specific file -->
<tool_call name="@coder" args='{"cmd":"git-diff","args":{"file":"main.go"}}'/>

<!-- Staged diff -->
<tool_call name="@coder" args='{"cmd":"git-diff","args":{"staged":true}}'/>
Displays the repository’s commit history.

​
Flags

FlagTypeRequiredDefaultDescription
--onelineboolNofalseCompact format (one line per commit)
--limitintNo10Maximum number of commits shown

​
Examples

<!-- Last 10 commits -->
<tool_call name="@coder" args='{"cmd":"git-log","args":{}}'/>

<!-- Last 5 commits in compact format -->
<tool_call name="@coder" args='{"cmd":"git-log","args":{"oneline":true,"limit":5}}'/>
Lists changed files in the repository (similar to git diff --name-only).

​
Flags

FlagTypeRequiredDefaultDescription
--stagedboolNofalseList only staged files

​
Examples

<!-- All changed files -->
<tool_call name="@coder" args='{"cmd":"git-changed","args":{}}'/>

<!-- Only staged files -->
<tool_call name="@coder" args='{"cmd":"git-changed","args":{"staged":true}}'/>
Lists the repository’s branches.

​
Flags

FlagTypeRequiredDefaultDescription
--allboolNofalseInclude remote branches

​
Examples

<!-- Local branches -->
<tool_call name="@coder" args='{"cmd":"git-branch","args":{}}'/>

<!-- All branches (local + remote) -->
<tool_call name="@coder" args='{"cmd":"git-branch","args":{"all":true}}'/>
Restores a file from its .bak backup, automatically created by write or patch.

​
Flags

FlagTypeRequiredDefaultDescription
--filestringYes—Path of the file to restore

​
Examples

<tool_call name="@coder" args='{"cmd":"rollback","args":{"file":"main.go"}}'/>
rollback only works if a corresponding .bak file exists. Backups are automatically created by the write and patch commands.
Removes .bak files created by the backup system.No required flags.

​
Examples

<tool_call name="@coder" args='{"cmd":"clean","args":{}}'/>

​
Transactional multipatch

When a refactor needs to touch multiple files as one unit (rename an identifier propagated across 5 files, update an import in every consumer, etc.), use multipatch instead of chaining patch calls. The contract:
1

Phase 1 — validation (no writes)

For each edit in declaration order, the engine loads the file, simulates the search→replace in memory, and verifies the search text is still present after prior in-flight edits to the same file. A failure on any edit aborts the transaction before any disk write.
2

Phase 2 — commit

Snapshot of each affected file in memory + write the new content. Any write failure restores all touched files from the snapshot.
3

Concurrency

Per-file mutex (keyed by absolute path), acquisition in sorted order — two transactions touching the same pair of files never deadlock. File permissions (chmod) are preserved across the rewrite.
{
  "cmd": "multipatch",
  "args": {
    "edits": [
      {"file": "internal/auth/login.go", "search": "loginV1", "replace": "loginV2"},
      {"file": "internal/auth/login_test.go", "search": "loginV1", "replace": "loginV2"},
      {"file": "cmd/server/main.go", "search": "auth.loginV1", "replace": "auth.loginV2"}
    ]
  }
}
Each edit applies its search→replace exactly once (strings.Replace with n=1). To replace multiple occurrences in the same file, declare multiple edits. Per-edit base64 encoding is supported ("encoding":"base64") for payloads with non-UTF8 bytes.

​
Backup System

@coder implements an automatic backup system to protect against unwanted changes.
1

Write or Patch

When you execute write or patch, the plugin checks whether the target file already exists.
2

Backup Creation

If the file exists, a copy is saved with the .bak extension (e.g., main.go -> main.go.bak).
3

Change Application

The new content is written (or the patch is applied) to the original file.
4

Rollback Available

At any point, you can use rollback --file main.go to restore the previous version from the .bak file.
5

Cleanup

Use clean to remove all .bak files when you no longer need the backups.
The backup is overwritten on each new write or patch operation on the same file. If you make multiple changes, only the version immediately before the last operation will be available for rollback.

​
Path Validation and Security

@coder applies several security validations to all file paths:

Workspace Boundary

All paths are resolved relative to the working directory (workspace). Attempts to access files outside the workspace are blocked (e.g., ../../etc/passwd).

Symlink Resolution

Symlinks are resolved before validation. A symlink pointing outside the workspace will be rejected, even if the apparent path is within the allowed directory.

Sensitive Paths

Paths to sensitive system files (e.g., /etc/shadow, /etc/passwd) are blocked by default, preventing read or write operations.

Dangerous Commands

The exec subcommand filters known destructive patterns such as rm -rf /, dd, fork bombs, and others. These commands are rejected before execution.

​
Complete Usage Example (in /coder)

In /coder mode, the assistant responds with a reasoning block followed by a tool_call. Here is a complete engineering workflow: 
<!-- 1. Understand the project structure -->
<tool_call name="@coder" args='{"cmd":"tree","args":{"dir":".","glob":"*.go"}}'/>

<!-- 2. Search where a function is defined -->
<tool_call name="@coder" args='{"cmd":"search","args":{"term":"func HandleRequest","dir":".","glob":"*.go"}}'/>

<!-- 3. Read the relevant file -->
<tool_call name="@coder" args='{"cmd":"read","args":{"file":"handler.go","start":15,"end":45}}'/>

<!-- 4. Apply a fix -->
<tool_call name="@coder" args='{"cmd":"patch","args":{"file":"handler.go","search":"return nil","replace":"return fmt.Errorf(\"missing parameter: %s\", name)"}}'/>

<!-- 5. Run the tests -->
<tool_call name="@coder" args='{"cmd":"test","args":{"dir":".","timeout":60}}'/>

<!-- 6. Check what changed -->
<tool_call name="@coder" args='{"cmd":"git-diff","args":{}}'/>

<!-- 7. If something went wrong, revert -->
<tool_call name="@coder" args='{"cmd":"rollback","args":{"file":"handler.go"}}'/>

​
JSON Recovery and Robust Parsing

@coder includes a JSON recovery system that automatically fixes malformed arguments generated by LLMs:

7 Recovery Strategies

Single quotes, unquoted keys, trailing commas, plain string wrapping, and more. See JSON Recovery for details.

Escaped Quotes in Shell

Improved handling of escaped quotes in shell commands, avoiding parsing failures when the model generates exec --cmd "echo \"hello\"".

Unicode Quote Normalization

Curly (typographic) quotes are automatically converted to straight quotes in code files, preventing compilation errors.

Concurrent Execution

Tool calls that operate on different files are executed in parallel (file-scoped parallelization), speeding up read and search operations.

​
Important Notes

@coder grants read/write power over files and command execution, all subject to rollback when requested. Use in trusted repositories.
Being builtin, @coder appears in /plugin list with the [builtin] tag. It cannot be uninstalled via /plugin uninstall.

​
Plugin @coder FAQ

Yes. The recommended format is JSON. Example:
<tool_call name="@coder" args='{"cmd":"read","args":{"file":"README.md"}}'/>
Use --search/--replace for simple, targeted substitutions at a single location in the file. Use --diff when you need to apply multiple changes at once or when the change involves adding/removing lines in different sections of the file. The diff can be encoded as text or base64.
@coder exec blocks dangerous patterns by default, such as rm -rf /, dd targeting disk devices, and fork bombs. The protection is automatic and requires no configuration.
Yes. The default is --max-bytes 200000 (200KB). You can also use --head or --tail to read only portions of the file. This prevents very large outputs from overwhelming the model’s context window.
The .bak backup is overwritten on each operation. Only the version immediately before the last write will be available for rollback. If you need full history, use git for version management.
Yes. The @coder plugin can be invoked in any mode that supports tool_calls. The /coder mode simply configures the system prompt to guide the model to use @coder as its primary tool.
Place a binary with the same name in the ~/.chatcli/plugins/ directory. It will take precedence over the builtin. To revert to the builtin, remove the custom binary and run /plugin reload.
It is not mandatory, but strongly recommended for write and patch when the content contains special characters, quotes, backslashes, or multiple lines. Base64 completely eliminates JSON escaping issues.

​
Next steps

Coder Mode

How /coder orchestrates @coder in a full ReAct loop.

Coder Security

Policies, allowlist, and execution governance.

Enhanced Permissions

40+ immune patterns and 90+ read-only allowlist.

JSON Recovery

7 strategies to recover malformed JSON in tool calls.

File Staleness

Track mtime + SHA-256 between read/write to avoid conflicts.

Cookbook: Fix tests

Practical recipe using @coder to autonomously fix tests.