CodeDocs Vault

File-to-Responsibility Map

Curated list of the files that matter. Skip the obvious (__init__.py re-exports, tests, docs) unless noted.

Entry Point

File Responsibility
pyproject.toml Dep list, strict mypy/pyright/ruff config, CLI entry declaration strix = strix.interface.main:main
strix/__init__.py Package metadata
strix.spec PyInstaller spec — bundled data files, hidden imports, exclusions
Makefile Dev commands (setup-dev, check-all, test-cov)
scripts/build.sh PyInstaller build driver, archives binary per platform
scripts/install.sh `curl
scripts/docker.sh Sandbox image management

Interface (CLI + TUI)

File Responsibility
strix/interface/main.py Top-level main(), argument parsing, warm-up, dispatch to CLI vs TUI
strix/interface/cli.py Non-interactive (headless) runner; Rich-based output; signal handling
strix/interface/tui.py Textual app; splash screen; agent tree; chat; vuln panel; stats
strix/interface/streaming_parser.py Parses partial <function>…</function> output for live TUI rendering
strix/interface/utils.py Target type inference, diff-scope resolution, repo cloning
strix/interface/tool_components/ Per-tool TUI renderers (BrowserRenderer, TerminalRenderer, ProxyRenderer, …)
strix/interface/assets/ TCSS stylesheets, banner art

Agents + LLM

File Responsibility
strix/agents/base_agent.py Async agent loop, waiting/timeout, inter-agent messaging, iteration limits, error handling
strix/agents/state.py AgentState pydantic model — messages, todos, sandbox handle, iteration counters
strix/agents/StrixAgent/strix_agent.py Specialization that pins the jinja template + default skills
strix/agents/StrixAgent/system_prompt.jinja The big one — ~500-line system prompt template with scope enforcement, refusal avoidance, multi-agent rules, tool-call format, skill injection
strix/llm/llm.py litellm wrapper: streaming, early-stop on </function>, prompt caching, token accounting, system-prompt render, skill loading
strix/llm/config.py LLMConfig — model, reasoning_effort, is_whitebox, interactive, scan_mode
strix/llm/utils.py Tool-call regex parser, legacy format normalization, model resolution map
strix/llm/memory_compressor.py LLM-driven conversation history compression at 90k tokens
strix/llm/dedupe.py LLM-driven vulnerability report deduplication by root cause

Tools

File Responsibility
strix/tools/registry.py @register_tool decorator, schema loading, get_tools_prompt()
strix/tools/executor.py execute_tool dispatcher (local vs. HTTP to sandbox), result formatting, screenshot extraction
strix/tools/argument_parser.py String → typed argument coercion based on function signatures
strix/tools/context.py ContextVar-based current-agent tracker
strix/tools/agents_graph/agents_graph_actions.py create_agent, agent_finish, send_message_to_agent, wait_for_message, view_agent_graph
strix/tools/browser/browser_actions.py Playwright-driven browser automation with screenshot return
strix/tools/browser/browser_instance.py Persistent browser state
strix/tools/browser/tab_manager.py Per-agent tab state
strix/tools/terminal/terminal_actions.py tmux-backed shell sessions with special-key handling
strix/tools/terminal/terminal_manager.py Session orchestration
strix/tools/terminal/terminal_session.py pyte-parsed session state
strix/tools/proxy/proxy_actions.py Caido GraphQL client — list/view/send/repeat requests, scope rules
strix/tools/proxy/proxy_manager.py Caido project / connection management
strix/tools/python/python_actions.py python_action(new_session/execute/close)
strix/tools/python/python_manager.py IPython REPL lifecycle
strix/tools/python/python_instance.py Per-session kernel
strix/tools/file_edit/file_edit_actions.py OpenHands ACI editor + list_files + search_files (ripgrep)
strix/tools/notes/notes_actions.py Scratchpad notes by category, wiki memory
strix/tools/reporting/reporting_actions.py create_vulnerability_report with CVSS, PoC, remediation
strix/tools/finish/finish_actions.py finish_scan — root-agent-only, validates all subagents complete
strix/tools/thinking/thinking_actions.py think(thought) — no-op CoT scratchpad
strix/tools/todo/todo_actions.py Todo list management
strix/tools/load_skill/load_skill_actions.py Dynamic skill loading, max 5 per agent
strix/tools/web_search/web_search_actions.py Perplexity sonar-reasoning-pro search
strix/tools/*/\*_schema.xml LLM-facing XML schemas — single source of truth for each tool's interface

Runtime / Sandbox

File Responsibility
strix/runtime/runtime.py Abstract Runtime base
strix/runtime/docker_runtime.py DockerRuntime — container lifecycle, port allocation, bearer-token minting, tar upload, recovery
strix/runtime/tool_server.py FastAPI server inside the sandbox — /execute, /register_agent, /health, per-agent cancellation
containers/Dockerfile Kali-based image with nmap/nuclei/sqlmap/ffuf/httpx/Caido/Playwright/tree-sitter/semgrep/etc.
containers/docker-entrypoint.sh Boot sequence: start Caido, install CA, set system-wide proxy, launch tool_server

Skills (Prompt Library)

Path Responsibility
strix/skills/__init__.py load_skills(), frontmatter stripping, max-5 validator, excluded-category filter
strix/skills/scan_modes/quick.md Time-boxed rapid-triage methodology
strix/skills/scan_modes/standard.md Balanced full-coverage methodology
strix/skills/scan_modes/deep.md Exhaustive "2000+ steps" methodology
strix/skills/coordination/root_agent.md Orchestration contract — root agent decomposes, doesn't test
strix/skills/coordination/source_aware_whitebox.md Whitebox triage stack + wiki-memory discipline
strix/skills/custom/source_aware_sast.md SAST-specific guidance (whitebox)
strix/skills/vulnerabilities/*.md 17 vuln-class playbooks (sql_injection, xss, idor, rce, ssrf, xxe, csrf, auth_jwt, path_traversal, open_redirect, business_logic, race_conditions, insecure_file_uploads, info_disclosure, mass_assignment, subdomain_takeover, broken_func_level_authz)
strix/skills/tooling/*.md 9 CLI-tool playbooks (nmap, naabu, subfinder, httpx, katana, ffuf, nuclei, sqlmap, semgrep)
strix/skills/frameworks/*.md fastapi, nestjs, nextjs framework guidance
strix/skills/protocols/graphql.md GraphQL-specific patterns
strix/skills/technologies/*.md firebase_firestore, supabase

Config / Telemetry / Utils

File Responsibility
strix/config/config.py Config class, env precedence, ~/.strix/cli-config.json load/save, resolve_llm_config() with strix/ model auto-routing
strix/telemetry/tracer.py Tracer class — JSONL + OTEL span emission, OTEL bootstrap
strix/telemetry/posthog.py scan_started / finding_reported / scan_ended / error events to us.i.posthog.com
strix/telemetry/utils.py TelemetrySanitizer — scrubadub + regex for secrets/PII; OTEL attribute pruning
strix/telemetry/flags.py STRIX_TELEMETRY / STRIX_OTEL_TELEMETRY / STRIX_POSTHOG_TELEMETRY kill switches
strix/telemetry/README.md Opt-out instructions
strix/utils/resource_paths.py get_strix_resource_path() — PyInstaller-aware file locator

Tests

Path Responsibility
tests/config/test_config_telemetry.py Config precedence, env-change detection, Traceloop vars
tests/telemetry/ Tracer JSONL output, sanitization, OTEL pruning
tests/tools/test_load_skill_tool.py Dynamic skill-load behavior
tests/tools/ (others) Argument parsing, agent-graph, tool registration
tests/llm/test_llm_otel.py No global side effects on litellm callbacks
tests/interface/ Diff-scope resolution

Notably missing: no agent-loop tests, no Docker integration tests, no skill-content validation.

Where to Start Reading

If you have 30 minutes and want to understand Strix end-to-end:

  1. README.md — 5 min — product context
  2. strix/agents/StrixAgent/system_prompt.jinja — 10 min — the single most important artifact in the codebase
  3. strix/skills/scan_modes/deep.md — 5 min — the methodology
  4. strix/agents/base_agent.py:152-260 (the loop) — 5 min
  5. strix/llm/llm.py:173-239 (generate + message construction) — 5 min

That's the heart. Everything else is plumbing.