How taasezer/taanos works
1. Overall shape
TaaNOS is a single Go CLI application with a thin command entrypoint and a set of internal subsystems that form a deterministic execution pipeline. The design goal is explicit in the README: AI is used only to infer intent, while actual system actions come from a hardcoded registry.
2. CLI entrypoint and command surface
cmd/taanos/main.go is the executable entrypoint. It likely wires CLI commands such as init, status, history, model, config, and version, plus mode flags like explain/guided/auto and dry-run. This layer is the user-facing boundary; everything else sits behind it.
3. Pipeline as the core orchestration boundary
internal/pipeline is the central coordinator. It defines stage abstractions and pipeline-level errors, which suggests the app is built as a sequence of well-defined phases rather than ad hoc command handling. This is the main structure you would diagram: request enters, moves through stages, then either executes or stops with validation/recovery.
4. Intent extraction is the only AI-facing step
internal/intent contains extractor.go, prompt.go, validator.go, and intent types. This subsystem turns natural language into a structured intent, probably via a local Ollama model as described in the README. Importantly, this layer does not execute commands; it only produces a normalized intent that downstream deterministic stages can consume.
5. Planner and deterministic action registry
internal/planner contains planner.go, registry.go, templates.go, and types. This is the deterministic mapping layer from intent to executable plan. The presence of a registry indicates fixed action definitions, and templates suggest it can render command sequences or step descriptions from those registered actions. This is the key safety boundary between interpretation and execution.
6. Validation and safety gating
internal/validator implements a separate safety gate, while internal/intent/validator.go likely validates extracted intent shape or confidence. The README’s “7-stage validator” implies multiple checks, such as privilege, disk space, dependency/tool presence, and risk assessment. Architecturally, validation sits between planning and execution and can block unsafe requests before any system mutation occurs.
7. Execution and rollback
internal/executor runs the approved plan, while internal/recovery provides rollback logic if a step fails. This split suggests forward execution and inverse actions are modeled separately, which is important for a diagram: execution is not just “run commands,” it is paired with compensating recovery steps to preserve system safety.
8. Context gathering and caching
internal/context includes analyzer.go, cache.go, and types. This subsystem likely collects system facts used by intent analysis, planning, and validation, and caches them to avoid repeated probing. It is the read-only observational layer feeding the rest of the pipeline with environment state.
9. OS and environment abstraction
internal/os contains platform detection and per-OS implementations for Linux, macOS, Windows, network, and system info. This is where cross-platform differences are normalized. It likely powers checks such as virtualization detection, RAM detection, package-manager availability, and root/admin privilege inspection, all of which affect setup and validation decisions.
10. User interaction and mode control
internal/interaction handles confirmations, prompts, and the guided/auto/explain behavior described in the README. This layer sits between pipeline stages and the user, controlling whether a step is merely described, explicitly approved, or automatically advanced.
11. Persistence and audit trail
internal/history stores execution records, and the README says this is backed by SQLite. That persistence layer records intent, outcomes, duration, and risk profile so the CLI can show past operations and provide traceability. For an architecture diagram, this is the durable audit boundary separate from the live execution path.
12. Setup and first-run bootstrap
internal/setup contains OS-specific detection plus a wizard. This subsystem is distinct from normal command execution: it initializes Ollama, selects an appropriate model, and configures the environment on first run. The bootstrap flow depends heavily on platform detection and machine characteristics.
13. Cross-cutting config and logging
config holds defaults and runtime configuration, while internal/logger standardizes log output and verbosity. These are cross-cutting support layers used throughout the CLI and pipeline, not standalone business subsystems.
14. Important external dependencies
The main external runtime dependency is Ollama, used locally for intent extraction. The rest of the system is intentionally deterministic and local: system commands, platform inspection, and SQLite-backed history are all part of the local machine boundary. The repository also includes installation scripts for Linux/macOS and Windows, plus packaged binaries, which support distribution but do not change the core architecture.
Main entry points: extractor.go Intent · main.go Main CLI · pipeline.go Pipeline · analyzer.go Context
Components 19
CLI
User-facing entrypoint and command surface.
- Main CLI · Executable entrypoint and command wiring.
cmd/taanos/main.go
Core pipeline
Deterministic request-to-action flow.
- Pipeline · Coordinates the staged execution flow.
internal/pipeline/pipeline.go - Stages · Stage abstraction used by the pipeline.
internal/pipeline/stage.go - Intent · Extracts structured intent from natural language.
internal/intent/extractor.go - Prompt · Prompt construction for intent inference.
internal/intent/prompt.go - Intent check · Validates extracted intent shape and quality.
internal/intent/validator.go - Planner · Turns intent into an executable plan.
internal/planner/planner.go - Registry · Hardcoded action registry for deterministic execution.
internal/planner/registry.go - Safety gate · Runs repository safety and feasibility checks.
internal/validator/validator.go - Executor · Executes approved plan steps.
internal/executor/executor.go - Recovery · Compensating actions and rollback handling.
internal/recovery/recovery.go
Support
Cross-cutting services and persistence.
- Config · Runtime defaults and configuration values.
config/defaults.go - Runtime config · Config loading and access helpers.
config/config.go - Interaction · Prompts, confirmations, and mode control.
internal/interaction/interaction.go - History · SQLite-backed execution history and traceability.
internal/history/store.go - Context · Collects and caches machine state for decisions.
internal/context/analyzer.go - Logger · Shared logging and verbosity control.
internal/logger/logger.go
Connections 22
- Main CLI → Runtime config: loads · CLI initializes runtime configuration.
- Main CLI → Logger: uses · CLI establishes logging early.
- Main CLI → Interaction: drives · CLI routes user-facing modes and prompts.
- Main CLI → Pipeline: starts · CLI hands requests to the pipeline.
- Pipeline → Stages: runs · Pipeline executes ordered stages.
- Pipeline → Context: reads · Pipeline consumes system context.
- Pipeline → Intent: requests · Pipeline begins by extracting intent.
- Intent → Prompt: builds · Prompting supports the AI intent step.
- Intent → Intent check: produces · Extracted intent is normalized and checked.
- Intent → Context: consults · Intent extraction can use gathered context.
- Intent → OS detect: consults · Platform facts may inform inference.
- Intent check → Planner: passes · Validated intent is handed to planning.
- Planner → Registry: resolves · Planner maps intent through fixed actions.
- Planner → Safety gate: submits · Planned actions are checked for safety.
- Safety gate → Interaction: asks · Safety decisions may require confirmation.
- Safety gate → Executor: approves · Approved plans proceed to execution.
- Executor → Recovery: guards · Failures trigger rollback handling.
- Executor → History: records · Execution outcomes are persisted for audit.
- Setup → OS detect: detects · Bootstrap uses OS and machine detection.
- Setup → Context: probes · Setup inspects environment capabilities.
- Context → OS detect: gathers · Context analysis relies on platform data.
- Runtime config → Config: inherits · Runtime configuration starts from defaults.