Home

Hosomaki Roadmap

---

Phase 1: Complete the Core

• watch <service> — real-time log tailing with live explanation of new errors as they appear

• why <exit-code> --service <name> — given a nonzero exit code, pulls surrounding context and explains the failure chain

• --output json on all commands for scripting and automation

• hosomaki ports — listening ports with process names, flags anything unexpected

• hosomaki crons — parses system and user crontabs, explains what each job does and when it last ran or failed

• hosomaki mounts — mount health, stale NFS mounts, disks approaching thresholds

• hosomaki timers — systemd timer inspection

---

Phase 2: Workflow Tools

These make Hosomaki useful in daily routines rather than just incident response.

• trace <process> — intelligent tracing of a running process: syscalls, resource usage, relevant events.
• summarise --since <time> — digest of everything that went wrong in a time window, grouped by severity
• compare --service <name> --boot -1 — compare a service's behaviour between the current and previous boot
• history — local log of past explanations so you can revisit insights without re-running the model. Stored in ~/.local/share/hosomaki/
• alias — save long invocations under short names. Example: hosomaki alias nginx-errors "explain --service nginx --lines 100". After that, hosomaki nginx-errors becomes a real command that internally runs hosomaki explain --service nginx --lines 100.
• env-check — scan /proc/<pid>/environ for common misconfigurations

---

Phase 3: Memory Layer

The biggest architectural milestone. Everything before this is stateless.

Storage

• SQLite + embeddings via Ollama's /api/embeddings as the default (no dependencies)
• pgvector as an opt-in for those who want it

What it enables

• Semantic search over past explanations (hosomaki history "OOM nginx" surfaces related past incidents even with different wording)
• Behavioural drift detection across snapshots over time, which is what makes audit genuinely useful long-term
• Better explanations for recurring issues: the model receives previous explanations and whether the issue reappeared, producing progressively sharper answers
• Foundation for honest prediction: predicting failures from a single snapshot is just pattern matching. With history it becomes real.

predict

Analyses patterns in your system's historical snapshots and log history to surface potential failures before they happen. The feature only becomes honest when it has enough history to detect patterns that are specific to your machine's behaviour.

hosomaki predict              # analyse current state against history, surface risks
hosomaki predict --since 7d   # limit pattern analysis to the last 7 days of history

Environment context and RAG

Currently, host environment data (distro, kernel, package manager, init system, security model) is collected at runtime and injected directly into every prompt as plain text. Once the memory layer exists, environment context becomes a better candidate for retrieval-augmented generation (RAG). Rather than appending the full environment block to every prompt, Hosomaki could store the host profile data as an embedding alongside historical snapshots, retrieve only the fields that are semantically relevant to the current query, and surface richer derived context.

---

Phase 4: Daemon Mode (hosomakid)

A background service that keeps an eye on the system continuously.

• Real-time anomaly detection
• Proactive warnings before things fail
• Continuous predictions based on the machine's own history
• Instant status and doctor responses (data is always current, no fresh collection needed)
• IPC interface that the CLI talks to: the daemon becomes the brain, the CLI is just a client

Note: Do not underestimate this phase, it might be the hardest one.

---

Phase 5: Multi-provider AI Support

The goal is flexibility without compromising the local-first principle.

• Ollama (current, always supported)
• OpenAI and Anthropic as opt-in remote providers
• Any OpenAI-compatible endpoint (LM Studio, llama.cpp, vllm, etc.) via a unified interface
• Opt-in cloud analysis path: logs are scrubbed and sanitised locally before anything leaves the machine, then analysed by a stateless remote agent. The user explicitly enables this. Nothing leaves by default.

---

Phase 6: Native UI Layer

The goal is to provide a graphical interface for users who prefer a visual workflow, while keeping Hosomaki CLI‑first and daemon‑driven.
The UI should be usable across all major desktop environments.

• GTK4 + Libadwaita for a clean, modern, Linux‑native interface
• Should work on GNOME, KDE, XFCE, Cinnamon, MATE, Budgie, COSMIC, and tiling WMs
• The UI is a thin client that communicates with hosomakid
• Dashboard with ystem health, recent explanations, active alerts
• Unified log viewer with filters and explanations
• File changes, service changes, permission diffs
• History for semantic search over past incidents
• Predicts risks, trends, recurring patterns
• Ports, crons, mounts, timers, env-check

Note: This feature is added after the daemon because the UI depends on continuous state, snapshots, drift detection, predictions, and history, all of which only exist once hosomakid is running. Before that, a UI would be just a visual wrapper around the CLI.