exoshell/docs/PHASES.md

Exoshell Phases

This roadmap turns the project vision into concrete build phases. The phases are intentionally ordered from the smallest useful shell-adjacent assistant toward the broader cognitive shell described in README.md and docs/DESIGN.md.

Phase 1: Shell-Adjacent Model Chat

Goal: ship a usable terminal program that lets a user talk to a model from PowerShell, bash, zsh, and similar shells without replacing the shell.

Core features:

• CLI entry point, likely exoshell, that runs as a normal terminal application.
• Provider configuration for at least one OpenAI-compatible backend.
• Local-first-compatible model adapter interface, even if the first implementation targets one backend.
• Interactive chat loop with streaming responses.
• Basic command suggestion formatting that distinguishes prose, shell commands, and warnings.
• Explicit copy/paste-oriented workflow: Exoshell suggests commands, the user remains responsible for execution.
• Cross-platform terminal behavior on Windows, macOS, and Linux.
• Shell-family awareness for PowerShell versus POSIX-like shells.
• Basic session transcript saved as markdown.
• Minimal config file for provider, model, default shell family, and notebook location.
• Clear error handling for missing API keys, provider failures, and interrupted requests.

User experience:

• User should be able to run "exo this is a prompt" and get a response, the program exiting

• User should be able to run exo (without a prompt) and have an open session, or "exo this is a prompt --stay" (or a more appropriate flag) to keep the shell/conversation open

• User should be able to pipe (bash) or powershell equivalent into exo and have it treated as a prompt, with the additional context of the command run that sent the pipe, cwd, etc.

  • For example, "ls | exo" should send a prompt similar to "{"command": "ls", "stdout": "foo bar baz", "cwd": "/foo/bar"}" and any relevant system prompts Non-goals:

• PTY control of the user's shell.

• Hotkeys that inject commands into the shell.

• Ambient context collection.

• Tree-sitter repo indexing.

• Long-term memory.

• Stances and personalities beyond a fixed default behavior.

• Autonomous command execution.

Exit criteria:

• A user can install/run Exoshell, configure a model backend, ask for help from a terminal, receive command suggestions appropriate to PowerShell or bash/zsh, and save the session transcript.
• The implementation has a small automated test suite for provider abstraction, shell-family prompt behavior, config loading, and transcript writing.

Phase 2: Context, Modes, and Operator Controls

Goal: make Exoshell feel like an operational overlay instead of a generic chat client.

Core features:

• Explicit context commands for adding files, command output, directory summaries, and pasted logs.
• Session-scoped context panel or context summary visible in the TUI.
• Stances such as operator, audit, teach, and quiet.
• Hotkeys for accepting, copying, explaining, and discarding suggested commands.
• Safer command suggestion UI with destructive-command detection and confirmation language.
• Context budget management with visible token or character estimates.
• Shell-specific command rendering and explanation for PowerShell and POSIX-like shells.
• Notebook improvements: title, timestamps, model metadata, commands suggested, and user-marked discoveries.
• Basic configuration profiles for different providers and shells.

Non-goals:

• Passive screen watching.
• Full PTY embedding.
• Repository-wide semantic indexing.
• Long-term memory outside user-controlled markdown/log files.

Exit criteria:

• A user can deliberately attach context, switch stance, inspect what context is being sent, and act on suggestions through predictable terminal controls.

Phase 3: Repo Awareness and Operational Notebooks

Goal: give Exoshell useful project awareness while keeping memory inspectable and scoped.

Core features:

• Repo detection and project-root selection.
• File tree summaries with ignore rules.
• Structural parsing for common languages using tree-sitter where practical.
• Commands to add source files, symbols, recent git changes, and test output to context.
• Markdown notebooks scoped by global, repo, task, and session.
• Searchable operational notes and discoveries.
• Runbook generation from session notes.
• Diff-oriented patch suggestions that require user review.
• Better uncertainty reporting through explicit signal strength.

Non-goals:

• Hidden long-term behavioral profiling.
• Blind patch application.
• Autonomous multi-file rewrites.

Exit criteria:

• A user can open a repo, ask informed questions about local code and recent command output, preserve useful notes, and generate reviewable runbooks or patch suggestions.

Phase 4: Follow Mode and Shell Integration

Goal: let Exoshell observe explicit shell activity and provide contextual help without becoming a replacement shell.

Core features:

• PTY or shell-hook integration strategy for supported environments.
• Follow mode that can ingest selected command history, stdout/stderr snippets, current directory, and exit status.
• User-visible controls for what is observed and retained.
• Hotkey workflows for sending command output to Exoshell.
• Optional paste-to-shell and paste-and-run flows with clear confirmation boundaries.
• Command outcome interpretation and next-step suggestions.
• Per-shell integration docs for PowerShell, bash, zsh, and fish.

Non-goals:

• Covert monitoring.
• Unreviewed execution.
• Replacing the user's shell configuration.

Exit criteria:

• A user can work in their normal shell while Exoshell follows explicitly permitted context and offers useful, nonintrusive operational guidance.

Phase 5: Tuning, Extensibility, and Local-First Depth

Goal: make Exoshell configurable, hackable, and effective with weaker local models.

Core features:

• Robust local model support through OpenAI-compatible local servers and/or dedicated adapters.
• Prompt and stance customization.
• User-editable command policies and safety rules.
• Extension points for tools, context providers, and notebook processors.
• Model routing by task type.
• Context compression and retrieval tuned for smaller models.
• Export/import of user configuration and notebooks.
• Advanced visual themes that remain restrained and terminal-native.

Non-goals:

• Cloud lock-in.
• Manager analytics.
• Personality behavior that compromises operational clarity.

Exit criteria:

• A technical user can tune Exoshell to their environment, run local-first workflows, and extend context/tool behavior without modifying core code.

Phase 6: Mature Cognitive Shell Overlay

Goal: converge on the broader vision: a calm, inspectable, practitioner-oriented cognitive shell environment.

Core features:

• Mature cockpit-style TUI with dense but readable operational instrumentation.
• Stable shell integrations across major platforms.
• High-quality repo, session, task, and notebook workflows.
• Reviewable command, patch, and runbook pipelines.
• Strong safety posture around destructive commands and hidden state.
• Comprehensive docs for installation, configuration, shell integration, model backends, stances, notebooks, and local-first operation.
• Packaging and release automation.

Exit criteria:

• Exoshell is a dependable daily-driver assistant for terminal-native practitioners who want AI augmentation while preserving control and understanding.