Skip to content

features.md

Latest commit

 

History

History
381 lines (322 loc) · 20 KB

features.md

File metadata and controls

381 lines (322 loc) · 20 KB
Raw

Autohand CLI Features

Autohand is an autonomous LLM-powered coding agent designed to work directly in your terminal.

Installation

  • npm: npm install -g autohand-cli
  • Homebrew: brew install autohandai/code/autohand-code
  • Standalone binaries (macOS, Linux, Windows)

Core Intelligence

  • Autonomous Agent: ReAct (Reasoning + Acting) loop for complex coding tasks
  • Multi-Model Support: OpenRouter integration (Claude, GPT-4, Grok, etc.)
  • Local Providers: Ollama, llama.cpp, MLX support via ~/.autohand/config.json
  • Context Awareness: Automatic project structure analysis

Interactive Experience

  • Slash suggestions (type / for commands)
  • File mentions (type @ for file autocomplete)
  • Shell Commands: Type ! to run terminal commands without LLM (e.g., ! git status, ! ls -la)
  • Smart Paste Detection: Paste large content (5+ lines) without breaking the prompt
    • Shows compact indicator: [Text pasted: N lines]
    • Full content sent to LLM on submit
    • Press Backspace to expand and edit pasted content
    • Works in modern terminals with bracketed paste mode
  • Rich terminal UI with status bar, spinners, colored output
  • Graceful error handling (ESC cancellation, invalid inputs)
  • Progress indicators (spinners)
  • Undo for file changes (via undoStack)
  • Responsive layout adapting to terminal size
  • Theme support (dark/light in config)
  • Syntax-highlighted code blocks
  • Interactive diff viewer (accept/reject/edit)
  • Interaction Modes: Cycle edit, plan, YOLO, and auto modes with Shift+Tab
  • IDE Integration: /ide command to connect to VS Code, Cursor, Zed, Antigravity
  • Redo for file changes
  • Search history and command palette

Session Management

  • Auto-save to ~/.autohand/sessions
  • Resume with /resume or autohand resume <id>
  • History tracking (interactions, tool outputs, agent thoughts)
  • /history for paginated session browsing
  • Session sharing and export

Settings Editor

The /settings command opens an interactive settings editor directly in the terminal.

  • Two-level category navigation across 8 categories: UI, Agent, Permissions, Network, Telemetry, Auto-mode, Teams, and Search
  • 35 configurable settings editable without leaving the TUI
  • Auto-save on change — values are written to ~/.autohand/config.json immediately
  • Type-aware inputs: booleans toggle on Enter, enums show a pick list, strings and numbers use inline editing, passwords are masked
  • Smart redirects: Provider config opens /model, theme opens /theme, language opens /language

Slash Commands

Command Description
/quit Exit the current session
/exit Exit the current session
/model Switch LLM models
/session Show current session details
/sessions List past sessions
/resume Resume a previous session
/new Start fresh conversation (with memory extraction)
/clear Clear conversation with automatic memory extraction
/undo Revert the last recorded agent file mutation and conversation turn
/memory View stored memories
/init Create AGENTS.md file
/agents Watch active Autohand sessions
/agents definitions List installed sub-agent definitions
/agents view Inspect direct and team runs
/agents-new Create new agent via wizard
/feedback Send feedback
/help Display help
/about Show information about Autohand
/whatsnew View and dismiss active CLI announcements
/formatters List available code formatters
/lint List available code linters
/completion Generate shell completion scripts
/export Export session to markdown/JSON/HTML
/history Browse session history with pagination
/ide Detect and connect to running IDEs
/plan Toggle plan mode
/theme Change color theme
/language Change display language
/login Authenticate with Autohand API
/logout Log out
/status Show session status and the signed-in Autohand plan
/usage Show project token activity and live Autohand AI 5-hour, 24-hour, weekly, and monthly quota windows when cli_usage_v2 is enabled
/statusline Configure composer status-line fields
/permissions Manage tool permissions
/hooks Manage lifecycle hooks
/extensions Validate, install, inspect, enable, disable, and diagnose Code extensions
/experiments Toggle experiments with an interactive checkbox list
/skills List and manage skills
/skills use Activate a skill
/skills install Install community skills
/skills new Create new skill
/mcp Interactive MCP server manager (toggle enable/disable)
/mcp install Browse and install compatible Official MCP Registry entries (stdio and HTTP)
/share Share current session
/sync Sync settings
/add-dir Add directories to workspace
/goal Set a session-attached persistent goal and continue successful auto-mode turns until it reaches a terminal state
/goal writer Draft one or more well-specified goals with the built-in $goal-writer skill
/goals, /goals view Open the live goals view with compact summaries and statuses
/goal view Alias for /goals view
/automode Start autonomous coding mode
/autoresearch Run replayable benchmark loops with adaptive decisions, history, replay, comparison, and Pareto analysis
/cc Context compaction
/search Search codebase
/settings Interactive settings editor — browse categories, edit values inline

Persistent goal files survive between conversations, while execution and usage accounting stay attached to the session that created or resumed the goal. A new session never takes work from another live session. When only queued work remains and no live peer owns it, bare /goal starts the next item; /goal resume remains the explicit control for paused or queued work.

Viewing and managing goals

If goals are disabled, run /experiments enable slash_goal. Open the panel with /goals, /goals view, or /goal view. Opening the view does not start queued work. Without an interactive panel, the view command returns a read-only text snapshot.

The panel groups the current goal, queued goals, and goals from other sessions. Each row shows a short, single-line preview and its status, keeping long objectives and pasted logs out of the overview. Editing loads the complete objective. Other-session rows are informational; this session's goal and shared queue are editable.

Close the panel with Ctrl+G (Cmd+G on macOS). The same shortcut opens it again, and the footer displays Ctrl+G close beside the editing controls. Closing the panel does not pause the goal.

Control Action
Up / Down, with an empty composer Select this session's goal or a queued goal
Enter on a selected row, or click its row Load the full objective into the composer
Enter while editing Save the updated objective without changing its queue position
Esc with a goal selected or being edited Clear the selection or cancel the unsaved edit

Esc does not close the goals view. When no goal selection or edit is active, it retains the normal composer and request-cancellation behavior.

Command Action
/goal <objective> Start a goal, or queue it if this session already has an active goal
/goal writer [rough objective] Draft goals with the built-in goal writer before creating them
/goals queue List queued goals and their IDs
/goals queue <objective> Add work to the queue
/goals edit <id> <objective> Update this session's goal or a queued goal by ID
/goals pause Pause this session's current goal
/goals resume Resume this session's goal, or start queued work when it has no current goal
/goals complete Complete the current goal and advance queued work when completion requirements are met
/goals clear Clear this session's current goal while retaining the queue and other sessions' goals
/goals templates List reusable goal templates

All subcommands accept either /goal or /goals. Bare /goals opens the view; bare /goal inspects or starts work according to the session state described above. For example, queue a follow-up task, inspect the queue, and reopen the panel:

/goals queue Review the release documentation
/goals queue
/goals view

Starting or resuming a goal uses the configured goal auto-mode behavior.

Experiment Switches

  • autohand experiments list prints a Codex-style table of feature id, lifecycle stage, and enabled state
  • autohand experiments status <feature> shows one feature, its config path, default, and restart note
  • autohand experiments enable <feature> and autohand experiments disable <feature> persist changes to config
  • autohand experiments refresh downloads remote feature flags from the Autohand API
  • /experiments opens an interactive checkbox list for toggling experiments from the TUI
  • /experiments is the interactive TUI surface for experiment changes
  • Remote feature flags are cached in ~/.autohand/feature-flags.json and refreshed after their API TTL expires
  • cli_usage_v2 is enabled by default and powers /usage, /usage weekly, and /usage monthly
  • experimental_browser_tools_v2 is disabled by default and requires a CLI restart; after an extension capability handshake it adds snapshot refs, typed waits, verified actions, and dedicated form tools
  • automatic_specialists is enabled by default and requires a CLI restart after an override; it resolves explicit specialist-team requests before the lead turn, renders the roster, aggregates catalog approval, and returns structured results for synthesis

Experimental: automatic specialists

Disable automatic_specialists with autohand experiments disable automatic_specialists or set features.automaticSpecialists: false in ~/.autohand/config.json, then restart the CLI. Explicit prompts that ask to bring, assemble, or run a team of named roles are resolved host-side; incidental mentions of agents or security do not trigger orchestration.

The experiment bundles product-interviewer, planner, debugger, security-auditor, and release-readiness. Catalog-backed gaps use one authorization request for the resolved roster and continue with local agents if installation is denied or the catalog is unavailable. Natural-language orchestration does not start /squad.

Experimental: stateful read safety

Stateful read safety ships as three ordered, default-off experiments. All three require a CLI restart after changing them:

  • read_state_ledger records the exact source-line coverage shown to the model in the active session without changing reads or writes.
  • read_state_dedup implies the ledger and replaces an eligible repeated unchanged read with a one-use stub. Repeating the call again restores the full content.
  • read_before_write implies both earlier increments and requires a complete, unchanged read_file view before a direct tool overwrites or removes an existing regular file. Partial, clamped, invalid-UTF-8, and stale views do not authorize a mutation.

Enable one increment with autohand experiments enable <feature> or /experiments enable <feature>. The equivalent config paths are features.readStateLedger, features.readStateDedup, and features.readBeforeWrite in ~/.autohand/config.json.

If compatibility problems prevent startup or a workflow from proceeding, launch the process with AUTOHAND_DISABLE_STATEFUL_READ=1. This emergency switch disables all three increments without changing the saved configuration.

Experimental: provider prompt caching

The prompt_caching switch (default off) adds a stable, opaque session-affinity hint to eligible provider requests so the provider can reuse unchanged prompt prefixes. It does not cache assistant responses locally and cannot move a provider's KV cache to another provider.

The initial candidate path is the ChatGPT OAuth Responses transport. Standard OpenAI Chat Completions and other providers are unchanged. Because the OAuth path targets a private backend, it remains experimental until current two-turn live evidence confirms that the field is accepted and cache usage is reported. An independent remote kill switch and a one-time exact-field fallback protect the request path.

Enable it with /experiments enable prompt_caching, or set features.promptCaching: true in ~/.autohand/config.json. The raw session ID is not sent to the provider. Cache read/write counts are retained only when the provider explicitly reports valid metrics; Autohand does not infer hits or savings.

Experimental: real-time token usage status

The experimental token_usage_status switch (default off) replaces the plain total-tokens counter in the working status line with a live breakdown of tokens sent up, tokens streamed down, and how full the model's context window is:

↑15.7k ↓3.2k · context: 6.0% (15.7k/262.1k)
  • ↑ is the cumulative input (prompt) tokens sent this session.
  • ↓ is the cumulative output (completion) tokens received this session.
  • context: N% (used/total) shows the most recent request's prompt tokens against the active model's context window. The window is resolved per model and works across every provider (OpenRouter, OpenAI, Anthropic, Bedrock, Vertex, and the rest). When a provider does not report usage the line reads unavailable; when the window is unknown only the ↑/↓ counts are shown.

Enable it with /experiments enable token_usage_status (or via the /experiments checkbox list), or set features.tokenUsageStatus: true in ~/.autohand/config.json. It updates in real time as the model works and takes effect immediately — no restart required.

Memory System

  • Project memory in .autohand/memory/
  • User memory in ~/.autohand/memory/
  • # trigger to store memories
  • Similarity detection (update vs duplicate)
  • Context injection for personalized responses
  • Automatic memory extraction on /clear and /new
    • LLM analyzes conversation history for reusable patterns
    • Classifies memories as user-level or project-level
    • Auto-saves without manual intervention
    • pre-clear hook event fires before extraction begins
    • View and manage extracted memories with /memory

Feedback System

  • Smart triggers (after tasks, on session end, gratitude detection)
  • Quick 1-5 ratings
  • Adaptive prompting with cooldowns
  • Follow-up questions based on rating
  • Local storage in ~/.autohand/feedback/
  • Manual /feedback command

Telemetry & Analytics

  • Opt-in telemetry collection (via ~/.autohand/config.json)
  • Session tracking (start, end, duration)
  • Tool usage analytics (success/failure, duration)
  • Error tracking with sanitized stack traces
  • Model switch tracking
  • Slash command usage
  • Offline batching (syncs when back online)
  • Session cloud sync (resume from any device)
  • Privacy-first: no PII, anonymous device IDs

Sub-Agent Architecture

  • Agent registry from ~/.autohand/agents/
  • Task delegation (delegate_task)
  • Parallel execution within the session thread budget (delegate_parallel); eight child threads by default, shared with teams and nested agents
  • /agents definitions for installed specialists and /agents view for runtime inspection

Tool System

  • File system: read, write, edit, create, delete, move, copy
  • Search: ripgrep, semantic search, symbol lookup
  • Git: status, diff, commit, branch, merge, rebase, cherry-pick, stash, worktree, remotes
  • Shell execution with output streaming
  • Package manager: npm add/remove with dev flag
  • Tool permission system for sensitive operations

Git Integration

  • Status, diff, checkout, apply patch
  • Branch operations (create, switch, delete)
  • Stash operations (stash, pop, apply, drop, list)
  • Cherry-pick with abort/continue
  • Rebase with abort/continue/skip
  • Merge with abort
  • Commit, add, reset
  • Remote operations (fetch, pull, push)
  • Worktree management (list, add, remove)
  • Advanced worktree automation (status, cleanup, parallel commands, sync, PR review)

Planning & Execution

  • Multi-step plan generation
  • Dry-run mode

Composable Workflows

  • Pipe Mode: echo 'code' | autohand 'explain'
  • JSON Output: --output-format stream-json or --json stream for NDJSON events; --json local for one final result object
  • Smart Stdin Detection: Auto-detects piped input vs TTY
  • Verbose mode with --verbose (progress to stderr)

Advanced Controls

  • Extended Thinking: --thinking [level] (extended/normal/none)
  • Yolo Mode: --yolo [pattern] for granular auto-approve
  • Auto-Approve Timeout: --timeout <seconds>
  • Custom System Prompt: Override or append system prompt

MCP Support

  • Connect to external MCP servers (stdio and HTTP transports)
  • Automatic tool discovery and namespaced registration
  • Server lifecycle management
  • Non-blocking startup: servers connect in background without delaying the prompt
  • Interactive /mcp manager: toggle servers on/off with arrow keys + space
  • /mcp install: browse and install validated stdio and HTTP entries from the Official MCP Registry
  • Agent MCP installation: search the catalog and request approval-gated installation by exact server ID
  • /mcp add/remove: manage servers from the command line
  • /mcp list: view all tools from connected servers

Developer Tools

  • Code formatting integration (prettier, black, rustfmt, gofmt, clang-format, shfmt)
  • Code linting integration (eslint, pylint, ruff, clippy, golangci-lint, shellcheck)
  • Shell completion scripts generated from the live CLI command tree (bash, zsh, fish), including autohand, autohand-code, and agent
  • Session export to markdown, JSON, and HTML

Planned Features

High Priority

  • Streaming text output with typewriter effect

Medium Priority

  • Plan modification (user can edit plans before execution)
  • Watch mode (auto-refresh on file changes)
  • Checkpoint system (save state between steps)
  • Rollback mechanism for failed operations
  • HTTP client tool for API requests
  • Redo for file changes
  • Search history and command palette

Future Considerations

  • LSP integration (go-to-definition, find-references)
  • Database tools (query execution, schema inspection)
  • Docker tools (build, run, inspect, logs)
  • VS Code extension (implemented as IDE integration via /ide)
  • CI/CD integration examples
  • Team workspaces with shared context

Platform Support

  • macOS
  • Linux
  • Windows

Security & Permissions

  • Confirmation prompts for destructive operations
  • Permission system with whitelist/blacklist
  • Three permission modes: interactive (default), unrestricted, restricted
  • Pattern-based whitelist (e.g., run_command:npm *)
  • Pattern-based blacklist (e.g., run_command:rm -rf *)
  • CLI flags: --unrestricted and --restricted
  • Local project permissions (.autohand/settings.local.json)
    • Approve once, don't ask again for this project
    • Per-file and per-command whitelisting
    • Merged with global settings (local takes priority)
  • File operation approval prompts (edit, write, delete)
  • Audit log of tool executions
  • Secret redaction in outputs

Performance & Reliability

  • Response streaming for immediate feedback
  • Automatic request retry with exponential backoff (configurable, max 5)
  • Request timeout configuration
  • User-friendly error messages (no raw provider errors exposed)
  • Caching layer for repeated tool calls
  • Lazy loading of tools