Skip to content

features.md

Latest commit

 

History

History
296 lines (256 loc) · 14.1 KB

features.md

File metadata and controls

296 lines (256 loc) · 14.1 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 git changes and last turn
/memory View stored memories
/init Create AGENTS.md file
/agents List sub-agents
/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
/usage Show project token activity by day, week, or month 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 community MCP servers
/share Share current session
/sync Sync settings
/add-dir Add directories to workspace
/goal Set, review, or refine a persistent session goal
/goal writer Draft one or more well-specified goals with the built-in $goal-writer skill
/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

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

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 up to 5 agents (delegate_parallel)
  • /agents command for discovery

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 from community MCP registry (12 curated servers)
  • /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