AutoCmd

A terminal-native AI assistant with file system and shell access. AutoCmd lives in your terminal, understands your working directory, and can read, write, and execute commands on your behalf — all through a rich Bubbletea TUI.

• AI-powered chat — Ask questions, run commands, and manipulate files using natural language.
• Saved commands — Ask the AI to save a useful command, then run it instantly with autocmd <name> — zero AI overhead, zero latency.
• Bash execution — The AI can run shell commands in your working directory, with interactive permission prompts for sensitive operations.
• File system access — Read, write, and edit files directly from the conversation. Changes are tracked with checksums for safety.
• Glob & grep search — Search across your codebase using familiar patterns.
• Background task management — Start long-running processes, list active tasks, and stop them on demand.
• Multi-provider LLM support — Works with Google Gemini and GitHub Models (Claude, GPT, Gemini). Extensible via MCP tools.
• Session management — Conversations are persisted per-directory. Switch, rename, or start fresh sessions.
• MCP tool support — Integrate external tools via the Model Context Protocol.
• Beautiful, Convenient TUI — Rendered with Bubbletea, Lip Gloss, and Glamour.
• Debug logging — Enable --debug to write a detailed log to ~/.config/autocmd/debug.log.

• Go 1.26.2+ — AutoCmd is installed via go install. If you don't have Go, download it from go.dev.
• An LLM provider API key — Google Gemini (API key) or GitHub Models (token).

go install github.com/Cyclone1070/autocmd@latest

This downloads, builds, and places the autocmd binary in your $GOPATH/bin (or $HOME/go/bin). Make sure that directory is on your PATH:

# Add to ~/.bashrc, ~/.zshrc, or equivalent
export PATH="$PATH:$(go env GOPATH)/bin"

autocmd -v

autocmd auth

Follow the interactive prompts to set up your API key. AutoCmd supports Google and GitHub providers.

autocmd model

Choose your default LLM model from the available options.

autocmd list all files in this directory

AutoCmd will start a session, process your request using the LLM, and show you the AI's reasoning and tool calls in real time.

autocmd -n "what's the largest file here?"

Or create a new session explicitly:

autocmd session new

autocmd history

When the AI runs a command you find useful, ask it to save it:

You: "save this command as 'status'"

Later, run it directly without invoking the AI:

autocmd status

Saved commands execute in a plain shell — no AI loop, no latency, no token cost.

autocmd [prompt] [flags]
autocmd [command]

When you pass a text prompt directly, AutoCmd runs it through the AI agent:

autocmd "explain the architecture of this project"

If no prompt is given, the help screen is displayed.

go test ./... -race -cover

Every implementation file has a companion test file — enforced per project convention. Tests use:

• Dependency injection unit test — inject mock implementations for all dependencies for production grade testing
• Mock-based LLM testing — deterministic agent behavior without external API calls
• Table-driven tests — following idiomatic Go patterns
• Race detection — enabled in CI to catch data races early
• Zero lint warnings — golangci-lint enforced in CI with strict configuration

AutoCmd stores its configuration in ~/.config/autocmd/. The default configuration can be customized with a JSON file at that path.

Key configuration areas:

By default, destructive operations (edit_file, write_file, bash) prompt for permission. Read-only tools (read, glob, grep) are allowed automatically.

AutoCmd supports the Model Context Protocol (MCP) for integrating external tools. Add an mcp.json configuration file to ~/.config/autocmd/ to register MCP servers. The AI will automatically discover and use those tools alongside its built-in capabilities.

Sessions are automatically scoped to your current Git repository root (or working directory). This means switching projects gives you a fresh context automatically.

autocmd uninstall

This removes the entire ~/.config/autocmd/ directory, including configuration files, authentication tokens, session data, and saved commands.

To also remove the binary:

rm "$(which autocmd)"

Dependencies flow inward: cmd/ → internal/* → domain/. The domain/ package has zero dependencies on the rest of the codebase.

cmd/            — Cobra CLI command definitions and dependency wiring
internal/
  agent/        — LLM agent loop, tool scheduling, summarization
  auth/         — Provider authentication (API keys, OAuth)
  command/      — Saved command storage
  config/       — Configuration loading, defaults, validation
  domain/       — Shared types, constants, events
  eventbus/     — In-process event bus for UI updates
  fs/           — File system abstraction
  logging/      — Structured logging
  permission/   — Per-tool permission resolution
  provider/     — LLM provider registry (Google, GitHub)
  session/      — Session persistence and lookup
  state/        — Application state management
  tool/         — Tool implementations (bash, read, write, edit, glob, grep, save, MCP)
  ui/           — Bubbletea UI models and renderers
  workflow/     — Orchestration logic (prompt, auth, model picker, etc.)

Key design decisions:

• Graph-runner state machine — agent orchestration uses composable graph nodes, not a monolithic loop. Each turn is an event-driven cycle through the graph.
• Event-driven UI — the agent never imports TUI code. It emits typed events over an in-process bus; the Bubbletea renderer subscribes independently.
• Tool abstraction — all tools implement a uniform interface with metadata, input schemas, and permission levels. The agent discovers available tools at runtime.

• Cobra — CLI framework
• Bubbletea — Terminal UI framework
• Lip Gloss — Style definitions
• Glamour — Markdown rendering
• Eino — LLM orchestration framework
• MCP Go — Model Context Protocol client
• golangci-lint — Strict lint enforcement, zero-warning policy
• GitHub Actions — CI pipeline (test + lint on every push)

MIT — Copyright (c) 2026 Cyclone1070