How ak4bento/capsule-shell works
Project type and purpose
• This is an AI-powered CLI assistant (an open-source tool) named “Capsule Shell.”
• Its purpose is to convert natural-language prompts into safe shell commands, show an explanation, prompt for confirmation, and optionally execute the extracted Bash code.
File structure
Top-level directories and files:
• cmd/
– root.go (defines the Cobra CLI commands and flags)
• chat/
– chat.go (handles communication with the OpenRouter API)
• internal/
– readonly.go (UI logic for non-execution mode)
– script.go (logic to extract valid Bash code blocks)
– ui.go (confirmation and execution prompts)
• main.go (initializes the CLI and kicks off the command flow)
• go.mod, go.sum (dependency configuration)
README for additional insights
• Uses Cobra for CLI parsing
• Calls the OpenRouter API (e.g., OpenAI) via chat/chat.go
• Has two modes: descriptive (-d) and execution (-x)
• Safety: only extracts and runs code from fenced Bash code blocks after confirmation
Components
a. User / Terminal
b. CLI Parser (Cobra – cmd/root.go)
c. Chat Service Module (chat/chat.go)
d. AI Provider (external OpenRouter API)
e. Response Handler & Extractor (internal/script.go)
f. UI & Confirmation Layer (internal/ui.go and internal/readonly.go)
g. Shell Execution Engine (invokes OS shell)
h. Optional: Configuration & Flags subsystem (Cobra flags, env vars)
Relationships and data flow
1. User enters a natural-language prompt + flags in the terminal.
2. Cobra Parser reads flags (-d, -x) and routes to main.
3. main.go calls Chat Service → sends prompt to OpenRouter API.
4. AI Provider returns a text response.
5. Response Handler extracts only the valid Bash code block.
6. UI Layer displays the AI explanation (descriptive mode) and shows the extracted command.
7. If execution flag is set, UI prompts user “Run this command? (y/n)”.
8. On confirmation, Shell Execution Engine spawns a subprocess to run the safe Bash command.
9. Execution result is returned and printed to the user.
Architectural patterns and design principles
• Modular separation: CLI, API client, parsing/extraction logic, UI, execution
• Single Responsibility: each package (cmd, chat, internal) has a clear role
• Safety first: “extract only fenced Bash code” principle, explicit confirmation
Detail
• Decision points (flags parsing, user confirmation).
• Role of internal/readonly.go vs. internal/ui.go for non-execution vs. execution flows.