Configuration & Environment

Relevant source files

The following files were used as context for generating this wiki page:

• src/core/agent.ts
• src/session/ProjectManager.ts
• src/core/toolManager.ts
• src/core/AutomodeState.ts
• src/core/AgentsMdUpdater.ts
• prd/historical-retrieval.md

The Configuration & Environment system in Autohand manages the operational settings, provider configurations, and persistent state required for the AI agent to function within a specific workspace. It encompasses local configuration files, environment-specific bootstrap processes, and project-level metadata stored in hidden directories.

The architecture is designed to support multiple LLM providers (OpenRouter, OpenAI, Ollama, llama.cpp, and MLX), workspace-specific instructions via AGENTS.md, and session-based state management that tracks progress through autonomous iterations. Sources: src/core/agent.ts:100-150, src/core/AutomodeState.ts:15-30

LLM Provider Configuration

Autohand supports dynamic switching and configuration of LLM providers. Configuration is stored centrally and accessed by the AutohandAgent to initialize provider-specific clients.

Supported Providers and Models

The system allows users to configure API keys, base URLs, and model IDs for various backends. Local providers like Ollama and llama.cpp use local URLs (e.g., http://localhost:11434), while cloud providers require API keys. Sources: src/core/agent.ts:515-650

Provider	Configuration Key	Primary Requirements
OpenRouter	openrouter	apiKey, model
OpenAI	openai	apiKey, model
Ollama	ollama	baseUrl, model
llama.cpp	llamacpp	baseUrl, port, model
MLX	mlx	baseUrl (Apple Silicon optimized)

Sources: src/core/agent.ts:515-645

Provider Initialization Flow

The following diagram illustrates how the agent initializes and updates its LLM provider based on user configuration.

The agent uses a ProviderFactory to generate the appropriate LLMProvider instance, which is then injected into the agent's runtime. Sources: src/core/agent.ts:490-510, src/core/agent.ts:1505-1525

Workspace Environment & Project Management

Autohand manages environment state at the workspace level, utilizing hidden directories and metadata files to maintain context across sessions.

Project Metadata and Knowledge

The ProjectManager maintains a persistent index of every project the agent interacts with. It hashes the project path to create a unique identifier in the ~/.autohand-cli/projects/ directory. Sources: src/session/ProjectManager.ts:25-50

• Project Index (index.json): Tracks display name, first seen date, session counts, and detected tech stack (languages, frameworks, tools).
• Knowledge Base (knowledge.json): Synthesizes successes and failures into "Best Practices" and "Anti-Patterns".
• Logs: successes.jsonl and failures.jsonl record every tool execution for historical retrieval.

Sources: src/session/ProjectManager.ts:55-85, prd/historical-retrieval.md:120-150

Local Environment Files

The agent recognizes several local files within the workspace to guide behavior:

• AGENTS.md: Primary file for project-specific instructions, tech stack definitions, and custom conventions.
• .autohand/: Directory containing session history, local skills, and the automode.local.md state file.
• .gitignore: Respects standard git ignore patterns when searching or listing files.

Sources: src/core/agent.ts:1140-1160, src/core/AutomodeState.ts:21-25

Auto-Mode State Management

For autonomous tasks, the system maintains a detailed state machine in .autohand/automode.local.md. This ensures that even if a session is interrupted, the progress, current iteration, and "Circuit Breaker" status are preserved. Sources: src/core/AutomodeState.ts:40-60

Circuit Breaker Logic

To prevent infinite loops or redundant failures, the environment tracks three specific thresholds:

Metric	Threshold	Purpose
No Progress	3 Iterations	Stops if the agent is stuck without modifying files.
Same Error	5 Iterations	Stops if the same error hash repeats consecutively.
Test-Only	3 Iterations	Prevents looping solely on test executions without fixes.

Sources: src/core/AutomodeState.ts:27-35, src/core/AutomodeState.ts:165-200

Configuration Data Structures

Agent Runtime Configuration

The AgentRuntime object holds the active state of the environment during execution. Sources: src/core/agent.ts:100-115

export interface AutomodeSessionState {
  sessionId: string;
  prompt: string;
  startedAt: string;
  currentIteration: number;
  maxIterations: number;
  status: AutomodeStatus;
  branch?: string;
  filesCreated: number;
  filesModified: number;
  completionPromise: string;
}

Sources: src/core/AutomodeState.ts:65-80

Environment Paths

The project uses standardized paths for different configuration layers:

• Global Skills: ~/.autohand/skills/
• Local Skills: <workspace>/.autohand/skills/
• Project Metadata: ~/.autohand-cli/projects/<project-hash>/

Sources: src/core/agent.ts:250-260, src/session/ProjectManager.ts:15-25

Workspace Discovery & Analysis

Upon startup, the ProjectAnalyzer performs an environment scan to detect the current project's configuration. This information is used to generate appropriate skills and update the AGENTS.md file.

Feature	Detection Logic
Tech Stack	Scans package.json, requirements.txt, Cargo.toml, or go.mod.
CI/CD	Checks for .github/workflows, .gitlab-ci.yml, or .circleci.
Package Manager	Detects lockfiles like bun.lockb, pnpm-lock.yaml, or yarn.lock.
Git Status	Runs git rev-parse --show-toplevel and git status.

Sources: src/skills/autoSkill.ts:140-250, src/core/AgentsMdUpdater.ts:70-100

Summary

The Autohand Configuration & Environment system provides a multi-layered approach to state and settings. By combining global user preferences with project-specific instructions (AGENTS.md) and autonomous state tracking (automode.local.md), the system creates a resilient environment where the AI agent can operate with high context awareness and safety controls like circuit breakers. Sources: src/core/agent.ts:100-130, src/core/AutomodeState.ts:260-300