{"key":"binkie_homelab_cli_project_context_2026_04_19","title":"Binkie Homelab CLI Project Context","content":"Project: Binkie Homelab CLI\nDate established: 2026-04-19\nCanonical project path: /home/svc-admin/ai-projects/projects/binkie-homelab-cli\nEarlier draft path: /home/svc-admin/ai-projects/binkie-lab-cli\n\nPurpose:\n- Build a local-first agent runtime that gives locally hosted models practical parity with frontier-model CLIs for local coding work, homelab operations, remote host inspection/maintenance, multi-step terminal workflows, and artifact generation/review.\n- The runtime is intended to work with frontier models, not replace them.\n- Design target: frontier model as planner/reviewer/escalation layer; local model as executor/operator; shared memory/artifacts between them.\n\nStrategic decision:\n- Preferred direction is to build a new runtime rather than keep bending OpenCode into a universal homelab operator.\n- OpenCode remains useful as a repo-focused coding agent, but not as the architectural center of gravity for a general homelab workhorse.\n\nCore requirements:\n- Persistent PTY-backed shell sessions\n- Truthful environment and execution-state reporting\n- Structured tools for file read/write/search/apply_patch\n- One-shot and persistent remote execution models\n- Host-aware remote operations\n- Safety and approval controls\n- Session logging, artifacts, and memory support\n\nHigh-level architecture:\n- CLI frontend\n- Agent orchestrator\n- Prompt layer and model adapter layer\n- Tool runtime\n- PTY and remote execution layer\n- Memory, logging, and safety layer\n\nKey principle:\n- Distinguish clearly between one-shot command execution and persistent PTY-backed sessions.\n- The runtime must never let the model infer fake continuity or fake shell state.\n\nTechnology direction:\n- Python preferred for runtime/orchestration\n- Ollama first for local model access\n- SQLite for early session/log/artifact state\n- optional Postgres/vector layer later\n\nSuggested project file layout and phased architecture are documented in the project docs.\n\nCurrent project documentation under canonical path:\n- /home/svc-admin/ai-projects/projects/binkie-homelab-cli/README.md\n- /home/svc-admin/ai-projects/projects/binkie-homelab-cli/AGENTS.md\n- /home/svc-admin/ai-projects/projects/binkie-homelab-cli/docs/01-project-brief.md\n- /home/svc-admin/ai-projects/projects/binkie-homelab-cli/docs/02-architecture.md\n- /home/svc-admin/ai-projects/projects/binkie-homelab-cli/docs/03-opencode-comparison.md\n- /home/svc-admin/ai-projects/projects/binkie-homelab-cli/docs/04-reuse-and-migration-plan.md\n- /home/svc-admin/ai-projects/projects/binkie-homelab-cli/docs/05-implementation-roadmap.md\n\nOpenCode relationship:\n- OpenCode comparison concluded that OpenCode is acceptable only with worktree bypass for local repo work and remains rejected for stateful remote SSH workflows.\n- Binkie Homelab CLI should be treated as a truth-first execution substrate and may optionally reuse ideas or isolated components from OpenCode later, but should not be based on OpenCode as its universal runtime.\n\nImmediate implementation posture:\n- Project is documentation-first right now.\n- No substantial code scaffold has been started yet.\n- The most useful next implementation phase, when work resumes, is Phase 0/1: scaffold, model adapter, filesystem/search/patch tools, PTY session manager, and session logging.\n\nCanonical doc intent:\n- README.md: project purpose and current status\n- docs/01-project-brief.md: goals, users, non-goals, success criteria\n- docs/02-architecture.md: runtime layers and design\n- docs/03-opencode-comparison.md: why not to use OpenCode as the foundation\n- docs/04-reuse-and-migration-plan.md: what to borrow vs rebuild cleanly\n- docs/05-implementation-roadmap.md: phased build plan\n\nCurrent status:\n- Planning documented and staged for future implementation.\n- Project is paused in favor of other higher-priority work, but should be easy to resume from the docs.","summary":"Binkie Homelab CLI is a planned local-first agent runtime for homelab and software-engineering work. It is intended to complement frontier models by serving as a trustworthy execution substrate for locally hosted models, with persistent PTY sessions, structured file and shell tools, remote host operations, safety controls, and memory/logging. The preferred direction is to build it as a new runtime rather than continue adapting OpenCode into a universal operator tool.","status":"active","namespace":"general:project","namespace_name":"general","namespace_tier":"project","tags":["binkie-homelab-cli","homelab","agent-runtime","local-models","pty","ssh","architecture","planning","opencode-comparison"]}