autocmd

command module
v1.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 2, 2026 License: MIT Imports: 1 Imported by: 0

README

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.

CI Go Report Card License

Features

  • 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.

Prerequisites

  • 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).

Installation

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"
Verify
autocmd -v

Quick Start

1. Authenticate with an LLM provider
autocmd auth

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

2. Select a model
autocmd model

Choose your default LLM model from the available options.

3. Run your first prompt
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.

4. Start a fresh session
autocmd -n "what's the largest file here?"

Or create a new session explicitly:

autocmd session new
5. View chat history
autocmd history

Saved Commands

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.

CLI Reference

Synopsis
autocmd [prompt] [flags]
autocmd [command]
Commands
Command Description
auth Manage authentication for LLM providers
completion Generate the autocompletion script for the specified shell
help Help about any command
history View chat history for the current session
info Show information about the current configuration and state
model Choose the default LLM model
session Manage conversation sessions
uninstall Remove AutoCmd and clean up configuration files
Global Flags
Flag Description
--debug Enable debug logging to ~/.config/autocmd/debug.log
-h, --help help for autocmd
-n, --new Start a new session for this prompt
Prompt Usage

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.

Testing

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

Configuration

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

Key configuration areas:

Section Description
tools File size limits, max iterations, per-tool permissions
providers LLM provider model lists (Google, GitHub)
ui Theme colors, chat window width, output window sizes

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

MCP Tool Support

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.

Session Management

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

Command Description
autocmd session Open the session picker UI
autocmd session new Create a new chat session
autocmd -n "your prompt" Run a prompt in a new session
autocmd history View conversation history

Uninstall

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)"

Architecture

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.

Built With

License

MIT — Copyright (c) 2026 Cyclone1070

Documentation

Overview

Package main is the entry point for the AutoCmd application.

Source Files

View all Source files

Directories

Path Synopsis
Package cmd implements the command-line interface for the application.
 Package cmd implements the command-line interface for the application.
internal
actionrouter
Package actionrouter handles routing of user actions to their respective handlers.
 Package actionrouter handles routing of user actions to their respective handlers.
agent
Package agent provides the core reasoning loop and tool execution logic.
 Package agent provides the core reasoning loop and tool execution logic.
auth
Package auth provides functionality for managing authentication credentials.
 Package auth provides functionality for managing authentication credentials.
command
Package command provides a persistent store for saved bash commands.
 Package command provides a persistent store for saved bash commands.
config
Package config handles application configuration loading and defaults.
 Package config handles application configuration loading and defaults.
domain
Package domain defines the core domain models and interfaces for the AutoCmd system.
 Package domain defines the core domain models and interfaces for the AutoCmd system.
eventbus
Package eventbus provides a central message hub for application events and updates.
 Package eventbus provides a central message hub for application events and updates.
fs
Package fs provides filesystem abstractions and implementations.
 Package fs provides filesystem abstractions and implementations.
logging
Package logging handles application-level error and debug logging to the local filesystem.
 Package logging handles application-level error and debug logging to the local filesystem.
permission
Package permission provides a mechanism for authorizing tool executions based on user-defined policies.
 Package permission provides a mechanism for authorizing tool executions based on user-defined policies.
provider
Package provider implements various LLM providers (Google, GitHub) for the application.
 Package provider implements various LLM providers (Google, GitHub) for the application.
randutil
runtimectx
session
Package session provides session management and persistence.
 Package session provides session management and persistence.
state
testutil
Package testutil provides common constants and utilities for application tests.
 Package testutil provides common constants and utilities for application tests.
tool
Package tool provides the tool registry and core tool implementations.
 Package tool provides the tool registry and core tool implementations.
tool/bash
Package bash provides tools for executing shell commands.
 Package bash provides tools for executing shell commands.
tool/edit
Package edit provides tools for reading, writing, and editing files.
 Package edit provides tools for reading, writing, and editing files.
tool/glob
Package glob provides tools for finding files and searching their content.
 Package glob provides tools for finding files and searching their content.
tool/grep
Package grep provides tools for finding files and searching their content.
 Package grep provides tools for finding files and searching their content.
tool/helper/content
Package content provides utilities for analyzing and manipulating file content.
 Package content provides utilities for analyzing and manipulating file content.
tool/helper/follow
Package follow provides utilities for following real-time updates to a file.
 Package follow provides utilities for following real-time updates to a file.
tool/helper/pagination
Package pagination provides utilities for paginating slices.
 Package pagination provides utilities for paginating slices.
tool/mcp
tool/question
Package question provides a tool for asking the user interactive questions.
 Package question provides a tool for asking the user interactive questions.
tool/read
Package read provides tools for reading, writing, and editing files.
 Package read provides tools for reading, writing, and editing files.
tool/save
Package save provides a tool for the AI agent to save bash commands for later reuse.
 Package save provides a tool for the AI agent to save bash commands for later reuse.
tool/service/checksum
Package checksum provides utilities for computing and managing file checksums.
 Package checksum provides utilities for computing and managing file checksums.
tool/service/executor
Package executor provides functionality for running OS commands with streaming output.
 Package executor provides functionality for running OS commands with streaming output.
tool/service/path
Package path provides path resolution and normalization utilities.
 Package path provides path resolution and normalization utilities.
tool/write
Package write provides tools for reading, writing, and editing files.
 Package write provides tools for reading, writing, and editing files.
ui
Package ui provides shared UI components and utilities for the AutoCmd terminal interface.
 Package ui provides shared UI components and utilities for the AutoCmd terminal interface.
ui/auth
Package authui provides the UI components for the authentication workflow.
 Package authui provides the UI components for the authentication workflow.
ui/history
Package history provides components for rendering the conversation history in the terminal.
 Package history provides components for rendering the conversation history in the terminal.
ui/info
Package info provides UI components for displaying system information and settings.
 Package info provides UI components for displaying system information and settings.
ui/model_picker
Package model_picker provides UI components for selecting LLM models.
 Package model_picker provides UI components for selecting LLM models.
ui/prompt
Package prompt provides the main interactive prompt and tool execution UI.
 Package prompt provides the main interactive prompt and tool execution UI.
ui/session_picker
Package session_picker provides UI components for selecting and managing chat sessions.
 Package session_picker provides UI components for selecting and managing chat sessions.
workflow
Package workflow implements the core business logic and state transitions for various system operations.
 Package workflow implements the core business logic and state transitions for various system operations.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.