12 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
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.