Guides · Extensions

Barebone CLI with extensions

Use --bare to reduce ambient startup behavior, then compose the CLI from explicitly installed extension packages whose files, scope, and contributions you can inspect.

What bare mode changes

Bare mode is a runtime boundary for explicit operation. It disables hooks, LSP startup, plugin and settings sync, attribution, auto-memory, background prefetches, keychain reads, AGENTS.md auto-discovery, community skill suggestions, notifications, telemetry, and slash commands. MCP and external agents load only when supplied explicitly through their corresponding flags.

Declarative extensions remain part of core runtime composition. User and project extension registries are still discovered before tool and agent prompt construction, and contributed actions still use the normal permission and tool-authorization path.

Lifecycle commands are top-level in bare workflows. Because slash commands are disabled in bare mode, use autohand extensions ... before or after the session rather than /extensions ... inside it.

Build a project-owned capability set

Project scope is the most reproducible choice for a barebone team workflow. The packages live under .autohand/extensions, so the workspace—not an individual developer's home directory—defines the extension snapshot.

cd /path/to/repository

autohand --path . extensions validate ../extensions/acme.code-health
autohand --path . extensions install ../extensions/acme.code-health --scope project
autohand --path . extensions validate ../extensions/acme.test-triage
autohand --path . extensions install ../extensions/acme.test-triage --scope project

autohand --path . extensions list --scope project
autohand --path . extensions doctor

Validate from the source directory first. Installation copies the package by default, so the runtime snapshot does not change merely because the author edits a neighboring checkout.

Inspect the effective package set

autohand --path . extensions list --scope project --json
autohand --path . extensions show acme.code-health --scope project --json
autohand --path . extensions show acme.test-triage --scope project --json
autohand --path . extensions doctor --json

Store the JSON reports as CI artifacts when the extension set is operationally important. They expose the package root, scope, linked/copied state, and active contribution names without running a contributed handler.

A healthy doctor report proves the registry parsed and resolved the packages. It does not prove that an external executable in a handler is installed or that a user will approve execution; exercise those conditions separately.

Start the minimal session

autohand --path . --bare

Inside the session, ask for a task that makes the contribution choice explicit, such as “Use the code-health reviewer to inspect src/ and return evidence-backed findings.” Confirm that Autohand advertises the expected tool and agent and that invoking the shell-backed tool produces the expected approval behavior.

Bare mode does not mean unrestricted mode. Do not add --unrestricted merely to remove prompts; the approval decision is part of validating that the extension follows canonical authorization.

Choose user scope only for personal defaults

A user package under ~/.autohand/extensions is also discovered in a bare session. It is useful for a developer's trusted personal helpers, but it makes the effective environment depend on that machine. If a project package has the same extension id, the project package replaces the user package as one complete unit.

For deterministic team runs: use unique project-owned ids, inspect both scopes with list, run doctor, and capture the expected ids and versions in repository documentation or CI policy.

Upgrade without partial activation

Prepare and validate the new package outside the installed directory. Then replace the copied project package atomically:

autohand --path . extensions validate ../extensions/acme.code-health-v1.1.0
autohand --path . extensions install ../extensions/acme.code-health-v1.1.0 \
  --scope project --replace
autohand --path . extensions show acme.code-health --scope project
autohand --path . extensions doctor

Start a fresh --bare session for the final proof. If the new package is invalid or conflicts with another contribution, it contributes nothing and appears in diagnostics instead of partially replacing the old active behavior.

Reset to the base CLI

autohand --path . extensions disable acme.code-health --scope project
autohand --path . extensions disable acme.test-triage --scope project
autohand --path . extensions list --scope project

# Remove after inspection
autohand --path . extensions remove acme.code-health --scope project --yes
autohand --path . extensions remove acme.test-triage --scope project --yes

Disabling preserves the package for inspection but removes its runtime contributions. Removing deletes only the installed copy and separate state; it does not mutate a source checkout used to create the package.