How starlessskynight/arkad-agent works
Arkad is a terminal-native AI coding agent. A user starts the Textual interface or legacy REPL, submits a prompt, and the agent selects tools, consults a configured model provider, then can inspect project context, edit files, run commands, and check its work. Supporting branches provide persistent sessions and memory, MCP servers, provider authentication, and an optional browser mirror. The README documents capabilities beyond the sampled excerpts; uncertain implementation links are omitted rather than inferred.
Main entry points: stream.py Turn streaming · app.py Textual TUI · tools Coding tools · main.py Rich REPL
Components 20
User interaction
- Textual TUI
arkad/tui/app.py - Rich REPL
arkad/main.py - Browser mirror
arkad/web/handler.py - Web server
arkad/web/server.py
Agent runtime
- Agent loop
arkad/loop.py - Turn streaming
arkad/repl/stream.py - Tool selection
arkad/tools/router.py - Turn rendering
arkad/repl/render.py - Shared state
arkad/state.py
Models and auth
- Provider client
arkad/auth/client.py - Provider catalog
arkad/constants/providers.py - Provider sign-in
arkad/auth/oauth_flow.py
Project capabilities
- Coding tools
arkad/tools - Project context
arkad/project_context.py - File changes
arkad/file_changes.py
State and integrations
- Session history
arkad/storage/sessions.py - Memory and skills
arkad/storage - MCP registry
arkad/mcp/registry.py - MCP management
arkad/mcp/manager.py
Other components
- User
Connections 21
- User → Textual TUI: starts default
- User → Rich REPL: starts legacy
- User → Browser mirror: uses browser
- Web server → Browser mirror: serves interface
arkad/web/server.py - Textual TUI → Agent loop: runs turns
- Rich REPL → Turn streaming: streams turns
arkad/main.py - Turn streaming → Provider client: requests model
arkad/repl/stream.py - Turn streaming → Tool selection: selects schemas
arkad/repl/stream.py - Tool selection → Coding tools: exposes tools
arkad/tools/router.py - Turn streaming → Turn rendering: renders output
arkad/repl/stream.py - Provider client → Provider catalog: resolves models
arkad/auth/client.py - Provider client → Provider sign-in: uses credentials
arkad/auth/client.py - Agent loop → Coding tools: invokes tools
arkad/tools/router.py - Coding tools → Project context: reads context
- Coding tools → File changes: edits files
- Rich REPL → Session history: loads history
arkad/main.py - Shared state → Session history: tracks sessions
arkad/state.py - Tool selection → MCP registry: includes MCP tools
arkad/tools/router.py - MCP management → MCP registry: manages connections
arkad/mcp/manager.py - Textual TUI → Shared state: uses shared state
arkad/tui/app.py - Web server → Textual TUI: mirrors console
arkad/web/server.py