Reference / Capabilities & Tools

Capabilities & Tools

Heddle is a local-first coding agent harness for real workspace tasks: inspect repositories, make bounded changes, verify results, preserve sessions, and keep agent work reviewable.

Core outcomes

Inspect repositories and explain unfamiliar codebases

Edit code and documentation inside the active workspace

Verify changes with builds, tests, shell commands, and review evidence

Carry work across multi-turn saved sessions instead of stateless prompts

Pin, rename, archive, and restore session-list state from the browser control plane

Switch between local project workspaces from the browser control plane

Learn durable workspace knowledge through catalog-backed memory

Connect user-configured MCP servers for ecosystem tools

Expose operator oversight through approvals, traces, and current diff review

Run bounded autonomous work through heartbeat scheduling

Workspace tools

Heddle exposes explicit tools instead of hiding workspace access behind vague automation. Tool calls are visible in the terminal, trace, or browser review surfaces.

list_files          # Inspect directories
read_file           # Read known file paths
search_files        # Search repo text with ignore-aware behavior
edit_file           # Apply direct text edits
delete_file         # Delete files or directories intentionally
move_file           # Move or rename files and directories
run_shell_inspect   # Run bounded read-oriented shell commands
run_shell_mutate    # Run approval-gated shell mutations

External and visual context

web_search: provider-backed hosted search for current external references or official documentation.
view_image: local image inspection for screenshots, diagrams, and browser-uploaded image paths.
MCP integrations: user-configured Model Context Protocol servers exposed through Heddle approvals and traces.
@file mentions: prompt-level file references that tell Heddle what to inspect first without blindly pasting full files into the prompt.
Direct shell: prefix with ! to run commands from chat, with approval when needed.

Runtime features

Saved multi-turn sessions under .heddle/

Session list management with create, switch, continue, rename, pin, unpin, archive, and close flows

Automatic and manual conversation compaction

Visible work plans for substantial tasks

Remembered per-project approvals for repeated safe actions

Memory candidate recording and maintainer-backed catalog updates

Request-size aware context tracking in chat

Interrupt and resume support for longer workflows

Serializable checkpoints for programmatic continuation

Control-plane oversight

The browser control plane adds saved session browsing, right-click pin/rename/archive actions with toast undo, live assistant streaming, tool progress, approval waits, workspace management, Git-backed current diff review, trace-backed turn history, heartbeat task management, and memory status. The review view is read-only: Git shows what changed now, while traces explain how a selected turn got there.

Current limits

Heddle is a coding agent harness and workspace runtime, not a general-purpose autonomous system.
Knowledge persistence uses explicit local catalogs so users can audit what Heddle learned.
The control-plane review surface is read-only, not an editable IDE-grade diff tool.
MCP server configuration does not enable a server by itself; users still choose which servers are active per workspace.
Web search is provider-backed rather than a crawler maintained inside Heddle.
.git and .heddle stay protected from broad accidental searches unless explicitly targeted.