mirror of
https://github.com/khodges42/exoshell.git
synced 2026-06-14 18:08:37 +00:00
readme
This commit is contained in:
parent
6a0737ead9
commit
4a1054de9b
371
README.md
371
README.md
|
|
@ -4,351 +4,96 @@ A cognitive shell for engineers who still want the controls.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Exoshell is a local-first cognitive shell designed for practitioners who want AI augmentation without surrendering operational awareness, understanding, or control.
|
Exoshell is a local-first, shell-adjacent assistant for practitioners who want AI help without giving up operational awareness or control. The shell remains primary; Exoshell suggests, explains, preserves context, and keeps the human in the loop. Exoshell is not designed for “vibe coding.”
|
||||||
|
|
||||||
Exoshell is not designed for “vibe coding.”
|
For the full project philosophy and design direction, read [docs/DESIGN.md](docs/DESIGN.md).
|
||||||
|
|
||||||
It is built for:
|
## Philosophy
|
||||||
|
|
||||||
* engineers who read logs
|
Exoshell exists because AI tooling should make skilled operators sharper, not less aware. It should preserve flow, reduce cognitive overhead, and help users understand the systems they are working on.
|
||||||
* people who tune their shell
|
|
||||||
* operators who want to stay sharp
|
|
||||||
* terminal users who care about flow-state
|
|
||||||
* practitioners who believe understanding systems still matters
|
|
||||||
|
|
||||||
Exoshell does not try to replace the operator.
|
The shell remains primary. Exoshell lives beside it as an operational overlay: it suggests commands, explains tradeoffs, surfaces uncertainty, records useful context, and leaves execution under human control.
|
||||||
|
|
||||||
It acts more like:
|
The project prefers visible systems over hidden automation, review over blind action, and deterministic tools over unnecessary AI. If `awk`, `jq`, `rg`, `git`, or a platform-native command is the right tool, Exoshell should say so.
|
||||||
|
|
||||||
* a cockpit HUD
|
Exoshell is local-first, terminal-native, inspectable, hackable, and practitioner-oriented. It is not an autonomous coding employee, a replacement shell, a manager dashboard, or a hidden context accumulation system.
|
||||||
* a systems copilot
|
|
||||||
* a cognitive exoskeleton
|
|
||||||
* an operational overlay for the terminal
|
|
||||||
|
|
||||||
The shell remains primary.
|
Sacred rule: enhance skill; do not replace it.
|
||||||
|
|
||||||
The human remains in control.
|
## Project State
|
||||||
|
|
||||||
⸻
|
Phase 1 is closed.
|
||||||
|
|
||||||
Philosophy
|
The current implementation supports the first shell-adjacent model chat milestone: a Rust CLI, OpenAI-compatible provider abstraction, PowerShell/POSIX shell-family selection, command-suggestion formatting, markdown transcripts, and a basic interactive REPL.
|
||||||
|
|
||||||
Modern AI tooling is rapidly drifting toward opaque automation:
|
The roadmap is tracked in [docs/PHASES.md](docs/PHASES.md). Phase 2 moves toward explicit context, modes, hotkeys, and stronger operator controls.
|
||||||
|
|
||||||
* giant autonomous rewrites
|
## Running Locally
|
||||||
* hidden context accumulation
|
|
||||||
* blind patch acceptance
|
|
||||||
* “just trust the agent”
|
|
||||||
* software generation without understanding
|
|
||||||
|
|
||||||
Exoshell takes the opposite position.
|
Phase 1 run instructions live in [docs/phase1_run.md](docs/phase1_run.md).
|
||||||
|
|
||||||
We believe:
|
Quick start:
|
||||||
|
|
||||||
* skill matters
|
```sh
|
||||||
* operational literacy matters
|
cargo run
|
||||||
* flow-state matters
|
```
|
||||||
* composability matters
|
|
||||||
* local-first tooling matters
|
|
||||||
* understanding systems matters
|
|
||||||
|
|
||||||
Exoshell exists to:
|
Use a config file:
|
||||||
|
|
||||||
* preserve awareness
|
```sh
|
||||||
* reduce cognitive overhead
|
cargo run -- --config path/to/config.toml
|
||||||
* accelerate understanding
|
```
|
||||||
* enhance practitioner capability
|
|
||||||
* keep the operator in the loop
|
|
||||||
|
|
||||||
Manual Supra, not Waymo.
|
Select a shell dialect:
|
||||||
|
|
||||||
⸻
|
```sh
|
||||||
|
cargo run -- --shell powershell
|
||||||
|
cargo run -- --shell posix
|
||||||
|
```
|
||||||
|
|
||||||
Core Principles
|
Exoshell suggests commands. It does not execute them.
|
||||||
|
|
||||||
Enhance Skill. Do Not Replace It.
|
## Quality Checks
|
||||||
|
|
||||||
Exoshell is intentionally designed for practitioners who want to deepen technical understanding rather than delegate it away.
|
```sh
|
||||||
|
cargo fmt --check
|
||||||
|
cargo test
|
||||||
|
cargo clippy --all-targets --all-features
|
||||||
|
```
|
||||||
|
|
||||||
The system should:
|
On Windows PowerShell, the Phase 1 smoke test is:
|
||||||
|
|
||||||
* teach
|
```powershell
|
||||||
* explain
|
powershell -ExecutionPolicy Bypass -File scripts\manual_phase1_startup.ps1
|
||||||
* preserve context
|
```
|
||||||
* surface uncertainty honestly
|
|
||||||
* encourage good tooling choices
|
|
||||||
* help users become more capable over time
|
|
||||||
|
|
||||||
The system should not:
|
## Documentation
|
||||||
|
|
||||||
* obscure systems
|
- [Design](docs/DESIGN.md): project philosophy, interaction model, non-goals, and technical direction.
|
||||||
* normalize blind automation
|
- [Phases](docs/PHASES.md): staged roadmap from Phase 1 through the mature cognitive shell overlay.
|
||||||
* encourage dependency
|
- [Phase 1 Run Guide](docs/phase1_run.md): local setup, config examples, CLI flags, and current limitations.
|
||||||
* hide execution
|
- [Versioning](docs/versioning.md): semantic versioning and release naming rules.
|
||||||
* replace understanding with throughput
|
- [Open Questions](docs/questions.md): decisions that still need explicit agreement.
|
||||||
|
|
||||||
⸻
|
## Contributing
|
||||||
|
|
||||||
The Human Keeps The Controls
|
Contributions are welcome, including from people who are learning Rust, terminal tooling, AI integration, or open source contribution workflows.
|
||||||
|
|
||||||
Exoshell prefers:
|
Before making a larger change, please read [docs/DESIGN.md](docs/DESIGN.md) so you understand the philosophy of the project. Exoshell is intentionally not an autonomous coding employee or a replacement shell. The core idea is to enhance skill, preserve understanding, and keep the operator in control.
|
||||||
|
|
||||||
* suggestions over autonomous action
|
Good contributions can be small:
|
||||||
* diffs over blind edits
|
|
||||||
* transparency over hidden state
|
|
||||||
* composability over abstraction
|
|
||||||
* instrumentation over “AI magic”
|
|
||||||
|
|
||||||
You should never feel:
|
- clarifying docs
|
||||||
|
- improving error messages
|
||||||
|
- adding focused tests
|
||||||
|
- tightening shell-specific behavior
|
||||||
|
- fixing platform issues
|
||||||
|
- turning roadmap items into small implementation tasks
|
||||||
|
|
||||||
“oh god, it’s doing something.”
|
If you are unsure where to start, open an issue or ask a question. It is fine to say what you are trying to learn; the project should be friendly to careful beginners as well as experienced systems people.
|
||||||
|
|
||||||
You should feel:
|
When changing release-visible behavior, also check [docs/versioning.md](docs/versioning.md).
|
||||||
|
|
||||||
* informed
|
## License
|
||||||
* aware
|
|
||||||
* amplified
|
|
||||||
* locked in
|
|
||||||
|
|
||||||
⸻
|
Exoshell is licensed under the GNU General Public License v3.0 or later. See [LICENSE](LICENSE).
|
||||||
|
|
||||||
Prefer Existing UNIX Tools
|
|
||||||
|
|
||||||
If awk is the correct solution, Exoshell should say so.
|
|
||||||
|
|
||||||
If jq is cleaner, Exoshell should prefer it.
|
|
||||||
|
|
||||||
If the shell already has a deterministic answer, Exoshell should not force AI into the workflow.
|
|
||||||
|
|
||||||
The goal is not:
|
|
||||||
|
|
||||||
“use AI everywhere.”
|
|
||||||
|
|
||||||
The goal is:
|
|
||||||
|
|
||||||
“use the right tool while preserving flow.”
|
|
||||||
|
|
||||||
⸻
|
|
||||||
|
|
||||||
Calm Software
|
|
||||||
|
|
||||||
Exoshell should feel like:
|
|
||||||
|
|
||||||
* a tuned workstation
|
|
||||||
* a mech cockpit
|
|
||||||
* a trusted operator console at 2am
|
|
||||||
|
|
||||||
Not:
|
|
||||||
|
|
||||||
* a productivity dashboard
|
|
||||||
* a startup control panel
|
|
||||||
* a gamified assistant
|
|
||||||
* an attention machine
|
|
||||||
|
|
||||||
The UI should be:
|
|
||||||
|
|
||||||
* restrained
|
|
||||||
* information dense
|
|
||||||
* aesthetically intentional
|
|
||||||
* terminal-native
|
|
||||||
* operationally calm
|
|
||||||
|
|
||||||
⸻
|
|
||||||
|
|
||||||
What Exoshell Is
|
|
||||||
|
|
||||||
Exoshell is:
|
|
||||||
|
|
||||||
* shell-adjacent
|
|
||||||
* terminal-native
|
|
||||||
* local-first
|
|
||||||
* practitioner-oriented
|
|
||||||
* composable
|
|
||||||
* inspectable
|
|
||||||
* hackable
|
|
||||||
* flow-state focused
|
|
||||||
|
|
||||||
Exoshell is inspired by:
|
|
||||||
|
|
||||||
* GNU / UNIX philosophy
|
|
||||||
* Emacs
|
|
||||||
* Vim / Neovim
|
|
||||||
* Arch Linux
|
|
||||||
* Gentoo
|
|
||||||
* tmux
|
|
||||||
* fish shell
|
|
||||||
* htop
|
|
||||||
* lazygit
|
|
||||||
* cockpit instrumentation
|
|
||||||
* workstation software
|
|
||||||
|
|
||||||
⸻
|
|
||||||
|
|
||||||
What Exoshell Is NOT
|
|
||||||
|
|
||||||
Exoshell is not:
|
|
||||||
|
|
||||||
* an autonomous coding employee
|
|
||||||
* a hidden surveillance layer
|
|
||||||
* a cloud lock-in platform
|
|
||||||
* a manager analytics dashboard
|
|
||||||
* “AI for everyone”
|
|
||||||
* a replacement for the shell
|
|
||||||
* a beginner-first abstraction layer
|
|
||||||
* a passive screen-watching assistant
|
|
||||||
|
|
||||||
Exoshell deliberately makes certain workflows harder:
|
|
||||||
|
|
||||||
* blind rewrites
|
|
||||||
* opaque automation
|
|
||||||
* no-review patching
|
|
||||||
* hidden execution
|
|
||||||
* dependency-forming abstractions
|
|
||||||
* automation without understanding
|
|
||||||
|
|
||||||
⸻
|
|
||||||
|
|
||||||
Interaction Model
|
|
||||||
|
|
||||||
The core Exoshell loop is:
|
|
||||||
|
|
||||||
human explores system
|
|
||||||
↓
|
|
||||||
Exoshell observes context
|
|
||||||
↓
|
|
||||||
Exoshell enhances awareness
|
|
||||||
↓
|
|
||||||
human requests action or insight
|
|
||||||
↓
|
|
||||||
Exoshell suggests command or interpretation
|
|
||||||
↓
|
|
||||||
human reviews/accepts/modifies
|
|
||||||
↓
|
|
||||||
Exoshell interprets results
|
|
||||||
↓
|
|
||||||
flow continues
|
|
||||||
|
|
||||||
Exoshell is designed to feel:
|
|
||||||
|
|
||||||
* collaborative
|
|
||||||
* instrument-like
|
|
||||||
* operational
|
|
||||||
* responsive
|
|
||||||
* trustworthy
|
|
||||||
|
|
||||||
Not:
|
|
||||||
|
|
||||||
* supervisory
|
|
||||||
* autonomous
|
|
||||||
* opaque
|
|
||||||
* overbearing
|
|
||||||
|
|
||||||
⸻
|
|
||||||
|
|
||||||
Features (Planned)
|
|
||||||
|
|
||||||
Shell-Adjacent Cognitive Overlay
|
|
||||||
|
|
||||||
Exoshell lives beside your shell instead of replacing it.
|
|
||||||
|
|
||||||
Command Suggestions
|
|
||||||
|
|
||||||
Paste, inspect, or execute suggested commands with hotkeys.
|
|
||||||
|
|
||||||
Signal Strength
|
|
||||||
|
|
||||||
Surface uncertainty honestly instead of hallucinating confidence.
|
|
||||||
|
|
||||||
Follow Mode
|
|
||||||
|
|
||||||
Ambient repo awareness and contextual operational guidance.
|
|
||||||
|
|
||||||
Operational Memory
|
|
||||||
|
|
||||||
Searchable markdown-based session notebooks and runbook generation.
|
|
||||||
|
|
||||||
Repo Awareness
|
|
||||||
|
|
||||||
tree-sitter powered structural understanding.
|
|
||||||
|
|
||||||
Stances
|
|
||||||
|
|
||||||
Operational behavior modes:
|
|
||||||
|
|
||||||
* operator
|
|
||||||
* audit
|
|
||||||
* teach
|
|
||||||
* drift
|
|
||||||
* quiet
|
|
||||||
* cockpit
|
|
||||||
|
|
||||||
Personalities
|
|
||||||
|
|
||||||
Optional expressive overlays:
|
|
||||||
|
|
||||||
* minimalist
|
|
||||||
* mech pilot
|
|
||||||
* magical girl
|
|
||||||
* sleepy night operator
|
|
||||||
* UNIX gremlin
|
|
||||||
|
|
||||||
Personality never overrides operational clarity.
|
|
||||||
|
|
||||||
⸻
|
|
||||||
|
|
||||||
Local-First
|
|
||||||
|
|
||||||
Exoshell is designed local-first.
|
|
||||||
|
|
||||||
We intentionally optimize for:
|
|
||||||
|
|
||||||
* weaker local models
|
|
||||||
* constrained contexts
|
|
||||||
* explicit orchestration
|
|
||||||
* inspectable behavior
|
|
||||||
|
|
||||||
If Exoshell works well with local models, stronger hosted models become even more effective.
|
|
||||||
|
|
||||||
Cloud backends are optional.
|
|
||||||
|
|
||||||
User sovereignty is not optional.
|
|
||||||
|
|
||||||
⸻
|
|
||||||
|
|
||||||
Technical Direction
|
|
||||||
|
|
||||||
Initial stack:
|
|
||||||
|
|
||||||
* Rust
|
|
||||||
* Ratatui
|
|
||||||
* Crossterm
|
|
||||||
* Tokio
|
|
||||||
* tree-sitter
|
|
||||||
* PTY integration
|
|
||||||
* markdown notebooks
|
|
||||||
* local model adapters
|
|
||||||
|
|
||||||
⸻
|
|
||||||
|
|
||||||
Cultural Direction
|
|
||||||
|
|
||||||
Exoshell is practitioner software.
|
|
||||||
|
|
||||||
It rewards:
|
|
||||||
|
|
||||||
* curiosity
|
|
||||||
* literacy
|
|
||||||
* tuning
|
|
||||||
* craftsmanship
|
|
||||||
* operational awareness
|
|
||||||
* intentional workflows
|
|
||||||
|
|
||||||
The goal is not to eliminate expertise.
|
|
||||||
|
|
||||||
The goal is to amplify it.
|
|
||||||
|
|
||||||
⸻
|
|
||||||
|
|
||||||
Sacred Rule
|
|
||||||
|
|
||||||
Enhance skill. Do not replace it.
|
|
||||||
|
|
|
||||||
Binary file not shown.
|
Before Width: | Height: | Size: 605 KiB After Width: | Height: | Size: 1.1 MiB |
Loading…
Reference in New Issue
Block a user