How waddle-io/ezshell works
ezShell diagnoses failed shell commands and turns natural-language requests into proposed commands that the user reviews and inserts; it does not execute fixes without user action. The Python CLI captures shell context, routes requests through a shared assistant/provider path, applies risk checks, and presents results in desktop, terminal, or inline interfaces. Its hosted web service supplies proxy-based AI access, device authorization, quotas, and account/admin capabilities. Some web routes and UI-to-API wiring were not sampled, so those connections are omitted rather than inferred.
Main entry points: handlers.ts Hosted API · chat_bridge.py Request bridge · main.py CLI dispatch · provider.py Provider selection
Components 26
Shell workflow
- CLI dispatch
src/main.py - Shell integration
src/core/shell_hook.py - Command capture
src/core/capture.py - Command execution
src/app.py - Desktop and TUI
src/ui/gui_window.py - Inline panel
src/ui/inline.py - Terminal rendering
src/ui/render.py
Assistant runtime
- Shell context
src/core/context.py - Request bridge
src/core/chat_bridge.py - Suggestion logic
src/core/suggest.py - Risk checks
src/core/safety.py - Provider selection
src/core/provider.py - Device proxy client
src/core/proxy_client.py - Direct Groq client
src/core/groq_client.py - User configuration
src/core/config.py
Hosted AI service
- Hosted API
web/lib/handlers.ts - Hosted model calls
web/lib/llm.ts - Quota and plans
web/lib/quota.ts - Server redaction
web/lib/redact.ts - PostgreSQL data
web/lib/db.ts
Accounts and operations
- Device authorization
web/app/api/v1/auth/device - Account dashboard
web/app/dashboard/page.tsx - Admin console
web/app/admin/page.tsx - Admin endpoints
web/app/api/v1/admin
Other components
- Terminal user
- Groq service
Connections 27
- Terminal user → Shell integration: invokes
- Shell integration → Command capture: captures runs
- Terminal user → CLI dispatch: starts
- CLI dispatch → Command execution: dispatches commands
src/main.py - Command execution → Shell context: reads context
src/app.py - Command capture → Shell context: supplies last run
src/core/context.py - CLI dispatch → Inline panel: dispatches suggestions
src/main.py - CLI dispatch → Desktop and TUI: opens desktop
src/main.py - Desktop and TUI → Request bridge: submits requests
src/ui/gui_window.py - Inline panel → Request bridge: requests suggestions
src/ui/inline.py - Request bridge → Shell context: builds request context
src/core/chat_bridge.py - Request bridge → Suggestion logic: gets suggestion
src/core/chat_bridge.py - Suggestion logic → Provider selection: queries provider
- Request bridge → Risk checks: checks proposed commands
src/core/chat_bridge.py - Provider selection → Device proxy client: selects hosted proxy
src/core/provider.py - Provider selection → Direct Groq client: selects direct mode
- Provider selection → User configuration: loads settings
src/core/provider.py - Device proxy client → Hosted API: posts requests
src/core/proxy_client.py - Hosted API → Hosted model calls: calls model
web/lib/handlers.ts - Hosted API → Quota and plans: checks usage
web/lib/handlers.ts - Hosted API → Server redaction: redacts input
web/lib/handlers.ts - Hosted API → PostgreSQL data: uses data store
web/lib/handlers.ts - Hosted model calls → Groq service: requests completions
- Terminal user → Device authorization: authorizes device
- Terminal user → Account dashboard: views account
- Terminal user → Admin console: manages service
- Admin console → Admin endpoints: uses admin features