Litegent is a lightweight, autonomous command-line AI agent written in Go for Linux environments. It executes an agentic loop — single-task or as a persistent interactive session — against any OpenAI-compatible LLM endpoint, equipped with built-in developer tools, robust context management, skills injection, live progress reporting, and comprehensive dual-format interaction logging. It is intentionally unconfined: there is no sandbox or path jail, by design.
Litegent takes an optional system prompt and configuration file (with sensible defaults under top_dir, whose default is ~/.litegent/), plus either a one-shot task prompt or an interactive session flag, and an optional skills directory:
-s <file>(optional): System prompt defining the agent's role, behavioral principles, and operating constraints. Defaults to<top_dir>/system.md; on a new session, if that file is absent, Litegent creates it with the built-in default system prompt.-p <file>: Task prompt for a single, non-interactive run. Required unless-iis set.-c <file>(optional): JSON configuration file defining model parameters, timeouts, logging settings, and context controls. When omitted, Litegent bootstraps from~/.litegent/config.json;top_dirin that file governs default locations.-i(optional): Run a persistent, multi-turn interactive session instead — task prompts are read one line at a time from stdin until/exit,/quit, or EOF. Conflicts with-p.-k <dir>(optional): Skills directory containing Markdown files with domain runbooks, procedures, and guidelines, injected into the system prompt. Defaults to<top_dir>/skillswhen present in config.-r <session-id>/--resume-last(optional): Resume an existing session by ID, or the most recently used one, instead of creating a new session.-v(optional): Stream live, human-facing progress to stderr as the loop runs, in addition to the files below.
When launched, Litegent:
- Ingests the system prompt and augments it with any discovered Markdown skills.
- Enters an agentic loop that invokes the LLM, parses requested tool calls, executes native tools directly on the host system, and feeds outputs back to the model — either once (single-shot) or repeatedly across turns with persistent conversation history (interactive,
-i). - Automatically protects LLM token budgets via
manage_context(configurable output truncation with disk spooling, sliding-window history pruning, and token-budget-gated conversation summarization). - Operates with zero external MCP servers by relying on built-in native tools:
bash: Linux command execution with timeout, non-interactive stdin, and pager/prompt neutralization.read_file,write_file,edit_file: Exact, surgical file manipulation.glob_search,grep_search: Fast filesystem pattern and content searches.
- Guards against getting stuck: a repeated-tool-call loop guard injects a corrective notice if the same call keeps producing the same result.
- Runs unconfined: none of the above tools are restricted to the invocation directory or any project root — they can read, write, and execute anywhere the host OS permissions allow. The audit logs (below) are the accountability mechanism in place of a sandbox.
- Creates a session per run (or resumes one), with all artifacts under
<top_dir>/<session-id>/:context.json: Durable, atomically updated effective conversation context, loaded on resume.logs/trace_<run-id>.jsonl: Machine-readable trace of user prompts, LLM calls, tool calls, and full tool results.logs/session_<run-id>.log: Parseable human-readable narrative of the exact flow.spool/: Full outputs that were too large to send to the model.
- Concludes autonomously when the task (or interactive session) is resolved, or a safety limit (
max_steps, per turn) is reached.
Ships as a single statically-linked Go binary (./install.sh) with no runtime dependencies; ./run.sh is a quick go build-then-run dev convenience wrapper.
Complete technical documentation is located under req/:
- Requirements Document — functional and non-functional requirements.
- Technical Specifications — architecture, module-by-module implementation detail, data flow.
- Deliverables Document — file-by-file inventory and acceptance criteria.
- Agent Guide (Engineering & Git Standards) — guidelines for AI and human developers.
- User Guide — installation, CLI reference, configuration, recipes, FAQ.
- Milestones Implementation Plan — the build order, reproducible from scratch.
- Changelog — release notes and migration details.
These documents are kept complete and current enough to rebuild Litegent from scratch without reading the source first.