mirror of
https://github.com/khodges42/exoshell.git
synced 2026-06-14 18:08:37 +00:00
100 lines
4.0 KiB
Markdown
100 lines
4.0 KiB
Markdown
# Exoshell
|
|
|
|
A cognitive shell for engineers who still want the controls.
|
|
|
|
|
|
|
|
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.”
|
|
|
|
For the full project philosophy and design direction, read [docs/DESIGN.md](docs/DESIGN.md).
|
|
|
|
## Philosophy
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
Sacred rule: enhance skill; do not replace it.
|
|
|
|
## Project State
|
|
|
|
Phase 1 is closed.
|
|
|
|
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.
|
|
|
|
The roadmap is tracked in [docs/PHASES.md](docs/PHASES.md). Phase 2 moves toward explicit context, modes, hotkeys, and stronger operator controls.
|
|
|
|
## Running Locally
|
|
|
|
Phase 1 run instructions live in [docs/phase1_run.md](docs/phase1_run.md).
|
|
|
|
Quick start:
|
|
|
|
```sh
|
|
cargo run
|
|
```
|
|
|
|
Use a config file:
|
|
|
|
```sh
|
|
cargo run -- --config path/to/config.toml
|
|
```
|
|
|
|
Select a shell dialect:
|
|
|
|
```sh
|
|
cargo run -- --shell powershell
|
|
cargo run -- --shell posix
|
|
```
|
|
|
|
Exoshell suggests commands. It does not execute them.
|
|
|
|
## Quality Checks
|
|
|
|
```sh
|
|
cargo fmt --check
|
|
cargo test
|
|
cargo clippy --all-targets --all-features
|
|
```
|
|
|
|
On Windows PowerShell, the Phase 1 smoke test is:
|
|
|
|
```powershell
|
|
powershell -ExecutionPolicy Bypass -File scripts\manual_phase1_startup.ps1
|
|
```
|
|
|
|
## Documentation
|
|
|
|
- [Design](docs/DESIGN.md): project philosophy, interaction model, non-goals, and technical direction.
|
|
- [Phases](docs/PHASES.md): staged roadmap from Phase 1 through the mature cognitive shell overlay.
|
|
- [Phase 1 Run Guide](docs/phase1_run.md): local setup, config examples, CLI flags, and current limitations.
|
|
- [Versioning](docs/versioning.md): semantic versioning and release naming rules.
|
|
- [Open Questions](docs/questions.md): decisions that still need explicit agreement.
|
|
|
|
## Contributing
|
|
|
|
Contributions are welcome, including from people who are learning Rust, terminal tooling, AI integration, or open source contribution workflows.
|
|
|
|
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.
|
|
|
|
Good contributions can be small:
|
|
|
|
- clarifying docs
|
|
- improving error messages
|
|
- adding focused tests
|
|
- tightening shell-specific behavior
|
|
- fixing platform issues
|
|
- turning roadmap items into small implementation tasks
|
|
|
|
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.
|
|
|
|
When changing release-visible behavior, also check [docs/versioning.md](docs/versioning.md).
|
|
|
|
## License
|
|
|
|
Exoshell is licensed under the GNU General Public License v3.0 or later. See [LICENSE](LICENSE).
|