AutoTerminal/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

AutoTerminal is an LLM-powered terminal assistant that converts natural language into shell commands. It's a Python CLI tool that uses OpenAI-compatible APIs to generate and execute terminal commands based on user input, with context awareness from command history and current directory contents.

Development Commands

Package Management

# Install dependencies (development mode)
uv sync

# Install package locally for testing
pip install --user -e .

# Uninstall
pip uninstall autoterminal

Running the Tool

# Using uv run (development)
uv run python autoterminal/main.py "your command request"

# After installation
at "your command request"

# With history context
at --history-count 5 "command based on previous context"

# Command recommendation mode (no input)
at

Building and Distribution

# Build distribution packages
python -m build

# Upload to PyPI (requires twine)
twine upload dist/*

Architecture

Core Flow

1. User Input → CLI argument parsing (main.py)
2. Configuration Loading → ConfigLoader/ConfigManager retrieve user settings from ~/.autoterminal/config.json
3. Context Gathering → HistoryManager fetches recent commands + glob current directory contents
4. LLM Generation → LLMClient sends prompt with context to OpenAI-compatible API
5. Command Execution → User confirms, then command executes via os.system()
6. History Persistence → Executed command saved to ~/.autoterminal/history.json

Key Components

autoterminal/main.py

• Entry point for at command
• Argument parsing and orchestration
• Two modes: command generation (with user input) and recommendation mode (without input)
• Uses glob.glob("*") to gather current directory context

autoterminal/llm/client.py

• LLMClient class wraps OpenAI API
• generate_command() constructs prompts with history and directory context
• Two prompt modes: default (user command) and recommendation (auto-suggest)
• System prompt includes recent command history and current directory files

autoterminal/config/

• ConfigLoader: Reads from ~/.autoterminal/config.json
• ConfigManager: Interactive setup wizard, validation, and persistence
• Required fields: api_key, base_url, model
• Optional: max_history, default_prompt, recommendation_prompt

autoterminal/history/

• HistoryManager: Persists commands to ~/.autoterminal/history.json
• Stores: timestamp, user_input, generated_command, executed flag
• get_last_executed_command() prevents duplicate recommendations

autoterminal/utils/helpers.py

• clean_command(): Strips quotes and whitespace from LLM output
• get_shell_history(count): Reads shell history from ~/.bash_history or ~/.zsh_history
  • Filters sensitive commands (password, key, token, etc.)
  • Handles zsh extended history format
  • Deduplicates commands (keeps last occurrence)
  • Returns up to N most recent commands

autoterminal/utils/logger.py

• Configures loguru for structured logging
• Console output to stderr (colored, configurable via AUTOTERMINAL_LOG_LEVEL env var)
• File output to ~/.autoterminal/autoterminal.log (rotation: 10MB, retention: 7 days)
• Logging levels: ERROR for console (default, production mode), DEBUG for file
• Enable verbose console logging: AUTOTERMINAL_LOG_LEVEL=INFO or DEBUG
• Disable file logging: AUTOTERMINAL_FILE_LOG=false

Configuration Storage

All user data lives in ~/.autoterminal/:

• config.json: API credentials and settings
• history.json: Command execution history
• autoterminal.log: Application logs (rotated at 10MB, compressed)

Installation Mechanism

pyproject.toml defines:

• Entry point: at = "autoterminal.main:main"
• Dependencies: openai>=1.0.0, loguru>=0.7.0
• Python requirement: >=3.10
• Build system: setuptools

Important Implementation Details

Context-Aware Command Generation

The LLM receives four critical context inputs:

1. Command History: Last N commands from AutoTerminal (user input + generated command pairs)
2. Directory Contents: Output of glob.glob("*") in current working directory
3. Shell History: Last 20 commands from user's shell history (bash/zsh) via get_shell_history()
4. Last Executed Command: Used in recommendation mode to avoid repeats

Two Operating Modes

1. Command Generation Mode (at "do something"):

   • Uses default_prompt from config
   • Generates command from user's natural language request

2. Recommendation Mode (at with no args):

   • Uses recommendation_prompt from config
   • Analyzes context to suggest next likely command
   • Returns empty string if context insufficient
   • Special logic to avoid recommending echo commands for listing files

Safety Mechanism

Commands are always displayed before execution with "Press Enter to execute..." prompt. User must explicitly confirm (Enter key) before execution via os.system().

Command Cleaning

LLM output is processed through clean_command() to remove:

• Leading/trailing quotes (single or double)
• Excess whitespace
• Prevents common LLM wrapping artifacts

Development Notes

When modifying prompts:

• System prompts are in config/manager.py defaults and configurable via config.json
• Recommendation prompt explicitly instructs against echo for file listing
• Context is appended to system prompt, not injected into user message

When working with history:

• History is capped at max_history entries (default: 10)
• Stored in reverse chronological order
• get_recent_history() returns oldest-to-newest slice for context

When extending LLM support:

• Client uses openai package with custom base_url
• Compatible with any OpenAI API-compatible service
• Temperature fixed at 0.1, max_tokens at 100 for deterministic short outputs

Configuration initialization:

• First run triggers interactive setup wizard
• Config validation checks for all required keys
• Command-line args (--api-key, --base-url, --model) override config file

Logging and Debugging:

• All modules use centralized loguru logger from autoterminal.utils.logger
• Production mode: Console only shows ERROR messages (default)
• Debug mode: AUTOTERMINAL_LOG_LEVEL=DEBUG at "command" shows all logs
• File logs: Always DEBUG level at ~/.autoterminal/autoterminal.log (unless disabled)
• View logs: tail -f ~/.autoterminal/autoterminal.log
• Key events logged: config loading, LLM calls, command execution, history updates, shell history reading

Shell History Integration:

• get_shell_history() automatically detects bash/zsh history files
• Detection strategy:
  1. Tries $HISTFILE environment variable
  2. Detects $SHELL to determine shell type (zsh/bash)
  3. Prioritizes history files based on detected shell
  4. Falls back to common locations (~/.bash_history, ~/.zsh_history, etc.)
• Sensitive keyword filtering prevents leaking credentials
• Shell history provides additional context beyond AutoTerminal's own history
• Failure to read shell history is non-fatal (returns empty list with warning)