9.0 KiB
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
- 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
⸻
- 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.
⸻
- 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.
⸻
- 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
⸻
- 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
⸻
- 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
⸻
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.