How tarkek/matrixcode works
matrixcode is a local coding assistant: a user enters a request in the Textual TUI, the agent sends context to an OpenAI-compatible llama-server, parses the response for tool calls, executes tools, and returns results to the model and chat. Its supporting capabilities include dynamically loaded tools, skills and slash commands; workspace safeguards and approvals; task plans and checkpoints; context compression, summaries and session continuation. Edges reflect the excerpts, SOURCE INDEX references and README; links for unsampled tool behavior are documented capabilities, not inspected call paths.
Main entry points: agent.py Agent loop · app.py Textual TUI · main.py Startup · registries.py Dynamic registries
Components 30
Startup and interface
- Startup
main.py - Textual TUI
ui/app.py - UI callbacks
ui/callbacks.py - Chat view
ui/chat.py - Status panels
ui/stats.py
Agent and model
- Agent loop
agent/agent.py - LLM client
llm/client.py - Call parser
core/parser.py
Tool runtime
- Dynamic registries
core/registries.py - Tool executor
execution/executor.py - Prompt skills
skills - Slash commands
commands
Workspace capabilities
- Workspace tools
tools - Shell execution
tools/run_shell.py - Checkpoints
tools/checkpoint.py - Task plans
tools/todo.py - Web fetch
tools/fetch_url.py - Project inspection
tools/project_info.py - Image display
tools/show_image.py - Workspace sandbox
core/sandbox.py - Child sandbox
core/childsandbox/sitecustomize.py - File post-checks
core/verify.py
Session support
- Context and memory
agent/context.py - Context compression
core/compression.py - History summary
core/summarize.py - Approval policy
core/policy.py - Session log
core/logger.py
Other components
- User
- llama-server
- Workspace files
Connections 36
- User → Textual TUI: enters request
README.md - Startup → Dynamic registries: loads modules
README.md - Startup → Textual TUI: starts UI
main.py - Textual TUI → Agent loop: starts turn
ui/app.py - Textual TUI → Slash commands: dispatches slash command
ui/app.py - Textual TUI → UI callbacks: uses callbacks
ui/app.py - UI callbacks → Chat view: updates view
ui/callbacks.py - Textual TUI → Chat view: renders chat
ui/app.py - Textual TUI → Status panels: updates status
ui/app.py - Agent loop → LLM client: requests completion
agent/agent.py - LLM client → llama-server: streams API
README.md - Agent loop → Call parser: parses calls
agent/agent.py - Agent loop → Tool executor: executes tool
agent/agent.py - Tool executor → Dynamic registries: resolves tool
execution/executor.py - Dynamic registries → Workspace tools: loads tools
README.md - Dynamic registries → Prompt skills: loads skills
README.md - Dynamic registries → Slash commands: loads commands
README.md - Tool executor → Workspace sandbox: guards tool access
execution/executor.py - Tool executor → Workspace files: reads before edits
execution/executor.py - Workspace tools → Workspace files: reads and edits
README.md - Shell execution → Workspace sandbox: uses sandbox
tools/run_shell.py - Workspace sandbox → Child sandbox: configures child Python
core/sandbox.py - Checkpoints → Workspace sandbox: checks paths
tools/checkpoint.py - Checkpoints → Workspace files: snapshots workspace
README.md - Task plans → Workspace files: stores task plan
README.md - Web fetch → llama-server: fetches external URL
README.md - Workspace tools → File post-checks: post-checks writes
README.md - Agent loop → Context and memory: builds prompt context
agent/agent.py - Agent loop → Context compression: compresses history
agent/agent.py - Agent loop → History summary: summarizes history
agent/agent.py - Startup → History summary: summarizes resumed history
main.py - Startup → Approval policy: sets startup policy
main.py - Agent loop → Session log: records events
agent/agent.py - Startup → Session log: opens session log
main.py - Project inspection → Workspace files: inspects project
README.md - Image display → Workspace files: displays image
README.md