Guides · Extensions
Choose an extension model
Start from who owns the runtime, what must execute, and how the capability should be distributed. Autohand offers several extension seams; each solves a different boundary.
Start with the ownership question
If users should remain inside the standard Autohand Code CLI, a CLI extension is usually the smallest coherent package. If you are building a product or service that owns agent lifecycle, UI, storage, or event handling, use the Code Agent SDK.
Do not choose based only on language preference. CLI Extension API v1 has a safe declarative layer and an explicitly trusted compiled runtime layer. The Agent SDK remains the right code-first surface when your application—not the CLI—must own execution, lifecycle, storage, and UI.
Compare the extension surfaces
| Surface | Choose it when | What it contributes | Primary owner |
|---|---|---|---|
| Declarative CLI extension | You need a versioned capability without package-code execution | Shell-backed tools, focused agents, and Agent Skills | Autohand's existing registries and permission path |
| Trusted CLI runtime extension | You need commands, terminal UI, shortcuts, flags, hooks, providers, or permission policy inside Autohand | Compiled JavaScript registered through Extension API v1 | Autohand process after explicit --trust |
| Code Agent SDK | You are embedding or orchestrating an agent in an application | Programmatic agent sessions, events, approvals, and app tools | Your process |
| Meta-tool | You need one local shell-backed tool and do not need package lifecycle | A persisted tool definition | User or project tool registry |
| External agent | You need one or more local agent definitions from a configured directory | JSON or Markdown agents | Agent registry configuration |
| Skill | You need reusable instructions, references, and workflow guidance for the model | Prompt-time knowledge and procedures | Skills system |
| MCP server | Tools must call a long-running service, API, database, or non-shell protocol | Remote or local service-backed tools | External MCP process |
| Hook | Behavior must react to session, tool, file, or command lifecycle events | Event-triggered commands | Hook configuration |
Use a CLI extension to package existing features
Declarative extensions package durable meta-tool, agent, and Agent Skill contracts. This is useful when one capability consists of evidence collectors plus the specialist or workflow that knows how to use them. For example, a test-triage package can declare run_focused_test and a failure-triage agent, while a workspace-brief package can declare evidence tools and a reusable $workspace-brief skill.
- One manifest supplies identity, version, description, and declared files.
- One lifecycle covers validate, install, inspect, enable, disable, diagnose, and remove.
- One provenance record shows which package owns each contribution.
- One security path keeps handler safety, shell escaping, permission decisions, hooks, and events consistent.
Add a trusted runtime only when the observable result requires a native CLI surface. Runtime code is not sandboxed, so review emitted JavaScript and bundled dependencies, validate without execution, and install with --trust.
Use the Agent SDK for code and product behavior
Choose the SDK when the agent is one component in a larger system and your process must own its control plane. Typical signals include an application database, custom authentication, domain APIs, a non-terminal real-time UI, queued jobs, multi-tenant policy, isolated deployment, or the need to interpret streamed events in host code.
A good boundary is to keep local, repository-specific affordances in CLI extensions and place application-owned control flow in the SDK host. The two can share naming and operational concepts without trying to ship the same artifact.
Decision examples
| Requirement | Recommended surface | Reason |
|---|---|---|
| Every repository should expose the same release-range command and release planner | CLI extension | A portable tool-and-agent package fits the standard CLI |
Developers should run /deploy and operate an Ink deployment menu | Trusted CLI runtime extension | The capability belongs inside the standard terminal experience |
Port an existing Pi package with a SKILL.md and TypeScript UI | Declarative skill plus reviewed runtime adaptation | The skill is directly portable; runtime registrations must be mapped and compiled |
| A support dashboard should launch an agent and stream progress to a browser | Agent SDK | The dashboard owns session lifecycle and UI events |
| A single developer wants a local formatter helper | Meta-tool | Package metadata and distribution may be unnecessary |
| An agent needs read access to a hosted issue tracker | MCP server or SDK tool | A service boundary is safer than a shell template |
| Run lint after every file change | Hook | The trigger is a lifecycle event, not a tool request |
| Teach the model a repeatable review rubric | Skill, or an agent prompt inside an extension | Choose based on whether it is general guidance or a callable specialist |
Prefer the smallest surface that preserves the contract. Start with one meta-tool or agent while exploring. Promote it into an extension when it needs versioning, distribution, ownership, coordinated install/removal, or multiple contributions.
For a migration workflow, continue to Adapt a Pi package.