Exoshell Design Document (Draft v0.1) Overview Exoshell is a local-first cognitive shell for practitioners. It is designed for engineers, operators, hackers, and technical users who want AI augmentation without surrendering understanding, agency, or operational control. Exoshell is not an autonomous coding employee. It is not designed to maximize software generation throughput at the expense of comprehension. It is not optimized for “vibe coding.” Exoshell exists to enhance skill, preserve flow-state, increase operational awareness, and keep the human firmly in control of the machine. The philosophy is simple: Manual Supra, not Waymo. The operator remains the pilot. ⸻ Core Principles 1. The Human Keeps The Controls Exoshell augments operators. It does not automate them away. The system should prefer: * suggestion over execution * visibility over hidden behavior * review over blind action * composability over abstraction * understanding over delegation Exoshell should never create the feeling: “oh god, it’s doing something.” The user should always feel: * oriented * informed * in control * capable of intervention ⸻ 2. Enhance Skill. Do Not Replace It. Exoshell is intentionally designed for practitioners who want to preserve and deepen technical understanding rather than delegate it away. The system should: * teach * explain * preserve context * encourage operational literacy * surface better tools when appropriate The system should not: * encourage dependency * obscure systems * normalize blind patch acceptance * encourage unreviewed giant rewrites Exoshell is anti-skill-atrophy software. ⸻ 3. Prefer Existing UNIX Tools Exoshell respects the shell ecosystem. If awk, sed, jq, rg, fd, grep, git, make, or existing UNIX tooling is the correct solution, Exoshell should say so. Example: Signal high: awk is likely the correct tool here. Suggested: awk '{print $3}' Exoshell should never force AI into workflows where deterministic tooling is superior. ⸻ 4. Preserve Flow-State Flow is sacred. Exoshell exists to preserve: * momentum * orientation * awareness * context * operational continuity The system should feel: * calm * responsive * intentional * instrument-like Not: * noisy * attention-seeking * chaotic * overbearing ⸻ 5. Calm Software Exoshell should feel like: * a tuned workstation * a mech cockpit * a trusted operator console at 2am Not: * a startup dashboard * a productivity app * a social platform * a gamified assistant The UI should be: * restrained * high signal * information dense without clutter * aesthetically intentional ⸻ 6. Visible Systems Exoshell should expose: * uncertainty * reasoning context * operational state * diffs * command execution * memory usage * signal quality Users should never be forced to trust hidden machinery. ⸻ Non-Goals Exoshell is explicitly NOT: * a “vibe coding” platform * a beginner-first abstraction layer * an autonomous software engineer * a manager dashboard * a telemetry surveillance platform * a cloud lock-in product * an AI social platform * an attempt to replace the shell * a passive screen-watching assistant * a hidden-memory behavioral profiling system Exoshell deliberately makes certain workflows harder: * blind autonomous rewrites * opaque execution * no-review patching * hidden context accumulation * dependency-forming abstraction * cloud-dependent workflows * automation without understanding ⸻ Inspirations Exoshell is directly inspired by: GNU / UNIX Philosophy * composability * inspectability * textual interfaces * user freedom * small understandable pieces Emacs * infinite hackability * modes * user ownership * software as living environment Vim / Neovim * speed * precision * modal interaction * mastery through repetition * config culture Arch Linux * explicit control * user responsibility * composability * “build your own machine” Gentoo * deep tuning * obsessive configurability * understanding through construction * practitioner culture tmux / htop / lazygit / fish * operational calm * cockpit UX * high information density * humane interaction ⸻ User Archetype The canonical Exoshell user is: * terminal-native * technically curious * workflow-oriented * skeptical of hidden automation * interested in improving over time * willing to tune their environment * interested in understanding systems rather than merely operating them Examples: * SREs * systems programmers * security engineers * infrastructure engineers * shell enthusiasts * local-first AI practitioners * people who think modern AI tooling is moving too fast toward opaque automation ⸻ Interaction Philosophy Primary Model Exoshell is shell-adjacent. The shell remains primary. Exoshell operates as: * a cognitive overlay * operational instrumentation * contextual augmentation The operator alternates fluidly between: * direct shell interaction * Exoshell prompting * command review * contextual follow mode The system should feel collaborative, not supervisory. ⸻ Core Interaction Loop human explores system ↓ Exoshell observes context ↓ Exoshell augments awareness ↓ human requests action or insight ↓ Exoshell suggests command or interpretation ↓ human reviews/accepts/modifies ↓ Exoshell interprets results ↓ flow continues ⸻ Command Semantics By default: * Exoshell suggests commands * the user executes them * execution is explicit * destructive actions require confirmation Actions may include: * paste suggestion * paste + execute * explain command * return stdout/stderr to model * generate patch * review diff ⸻ Signal Strength Exoshell surfaces uncertainty as “signal strength.” Examples: * signal: weak * signal: medium * signal: high Low-confidence claims should be clearly surfaced. The system should prefer: * clarification * scoped suggestions * partial certainty over hallucinated confidence. ⸻ Stances Stances define operational behavior. Examples: * operator * audit * drift * teach * quiet * cockpit Stances affect: * verbosity * interruption frequency * skepticism * pacing * explanation depth * operational posture Stances are NOT personalities. ⸻ Personalities Personalities define aesthetic and expressive behavior. Examples: * minimalist * mech pilot * magical girl * sleepy night operator * UNIX gremlin Personality affects: * wording * cadence * flavor * atmosphere Personality should never compromise: * operational clarity * structured output * shell composability ⸻ Memory Philosophy Memory is operational, not behavioral. Exoshell should remember: * repo structure * workflows * troubleshooting knowledge * active task context * useful operational discoveries Memory should NOT silently accumulate: * invasive behavioral profiling * emotional manipulation data * opaque long-term surveillance context Memory should be: * inspectable * scoped * editable * searchable * removable Memory scopes may include: * global * repo * task * session * ephemeral --- ## Context Philosophy Context is a first-class system within Exoshell. Most AI systems accumulate context implicitly through hidden memory, opaque retrieval systems, session state, telemetry, or behavioral profiling. Exoshell rejects this model. Context should be explicit. The operator should always be able to answer: * What information is being sent to the model? * Where did it come from? * Why is it present? * How large is it? * How can I remove it? Context is not hidden machinery. Context is instrumentation. ### Context As Cargo Exoshell treats context as cargo carried into a conversation. The operator chooses what to bring. Examples include: * files * command output * logs * notes * repository summaries * notebook entries * search results * git state Context should never silently appear. The operator should deliberately attach information when it becomes useful. ### Inspectability All active context should be visible. The user should be able to inspect: * source * size * type * age * priority * inclusion status before a request is sent to a model. The system should make context visible enough that an operator can reason about it the same way they reason about shell pipelines. ### Provenance Every context entry should retain provenance. The operator should be able to determine: * where context originated * when it was added * how it entered the session Examples: * manually pasted * loaded from a file * generated from git * generated from search * imported from a notebook Context without provenance is difficult to trust. ### Explicit Inclusion Possessing context and sending context are separate concepts. A context entry may exist within a session without being included in model requests. Operators should be able to: * enable context * disable context * pin context * prioritize context * remove context without destroying underlying information. ### Context Budgets Context is a finite resource. Exoshell should expose: * approximate token usage * approximate character usage * pruning decisions * compression decisions Users should never be surprised by context loss. If context must be reduced, the system should explain: * what was removed * why it was removed * what remains ### Context Is Not Memory Context and memory serve different purposes. Context is active operational state. Memory is retained knowledge. Context is temporary, task-oriented, and immediately relevant. Memory is persistent, searchable, and intentionally preserved. Exoshell should maintain a clear boundary between the two. ### Operator Ownership The operator owns context. Not the model. Not the application. Not a hidden retrieval system. Context should remain: * visible * editable * removable * exportable * inspectable at all times. A practitioner should never need faith to understand what information Exoshell is using. The system should make context obvious enough that trust emerges naturally from visibility. ⸻ Logging Philosophy Logs exist for: * transparency * operational continuity * searchable notes * runbook generation * learning * debugging Logs should be: * human-readable * text-based * compact by default * optionally verbose The preferred format is markdown-oriented notebook logging. Exoshell should preserve: * discoveries * command outcomes * architectural observations * troubleshooting notes Not raw “session replay.” ⸻ Local-First Philosophy Exoshell is designed local-first. Reasons: * user sovereignty * reliability * privacy * hackability * reduced lock-in * stronger runtime design pressure Cloud models are supported as optional backends, not architectural assumptions. Designing for weaker local models encourages: * better orchestration * better context handling * better uncertainty semantics * better UX ⸻ Visual Language Exoshell should feel like: * a mech cockpit * a terminal workstation * a tactical HUD * an operator console The visual language should emphasize: * restrained palettes * monochrome foundations * selective highlights * tasteful box drawing * dense but readable layouts * calm instrumentation Not: * dashboard clutter * excessive animation * startup aesthetics * “AI toy” visual language ⸻ Technical Direction (Initial) Likely stack: * Rust * Ratatui * Crossterm * Tokio * tree-sitter * PTY integration * markdown-based logging * local model adapters * OpenAI-compatible providers The shell remains external in v1. Exoshell lives beside the shell rather than replacing it. ⸻ Cultural Direction Exoshell is practitioner software. It should encourage: * workflow craftsmanship * configuration culture * literacy * experimentation * user ownership * local-first values * composability * sharing tuned environments The project should resist: * enshittification * surveillance incentives * cloud dependence * manager-oriented analytics * skill erosion Exoshell should feel: * configurable like Emacs * precise like Vim * intentional like Arch * obsessively tunable like Gentoo ⸻ Sacred Rule Enhance skill. Do not replace it. Everything in Exoshell should reinforce this principle.