singularity-forge/docs/dev/FILE-SYSTEM-MAP.md

sf File System Map

Maps every source file to its system/subsystem labels

---

System Labels Reference

Label	Description
Agent Core	Core agent loop, session lifecycle, SDK factory
AI Providers	LLM provider implementations (Anthropic, OpenAI, Google, etc.)
API Routes	Next.js API route handlers (web server)
AST	Abstract Syntax Tree search/rewrite via tree-sitter + ast-grep
Async Jobs	Background bash job management
Auth / OAuth	Authentication, OAuth flows, token storage
Auto Engine	SF autonomous execution loop, dispatch, supervision
Bg Shell	Background process / interactive shell management
Browser Tools	Playwright-based browser automation extension
Build System	Scripts for build, packaging, version management, CI
CLI	Command-line entry points and argument parsing
CMux	Tmux/multiplexer session integration
Commands	SF slash/sub-command routing and handlers
Compaction	Context token reduction and summarization
Config	Paths, defaults, models, preferences, constants
Context7	Library documentation fetching extension
Doctor / Diagnostics	Health checks, forensics, skill health
Event System	Event bus, publication/subscription
Extension Registry	Extension discovery, manifests, enable/disable
Extensions	Extension loader, runner, project trust, hooks
File Search	grep, glob, fd — file and content discovery
SF Workflow	Core SF planning/execution workflow engine
Google Search	Web search via Google API
Headless Mode	Non-interactive / scripted command execution
Image Processing	Image decode, resize, encode, clipboard images
Integration Tests	Smoke, fixture, live, regression test suites
Loader / Bootstrap	Startup initialization, extension sync, tool bootstrap
LSP	Language Server Protocol client and multiplexer
Mac Tools	macOS-native utilities (Swift CLI)
MCP Server/Client	Model Context Protocol server and client
Memory Extension	In-session memory pipeline and storage
Migration	Data and config migration tools
Modes	Interactive TUI, Print, RPC, and Web modes
Model System	Model discovery, resolution, routing, registry
Native / Rust Tools	N-API Rust engine modules
Node.js Bindings	TypeScript wrappers around Rust N-API modules
Onboarding	First-run wizard and setup flows
Permissions	Permission management for tools and trust
Remote Questions	Remote prompting via Slack, Discord, Telegram
Search the Web	Brave/Jina/Tavily-based web search extension
Session Management	Session file I/O, branches, fork trees
Skills	Skill tool registration, health, telemetry
Slash Commands	Command boilerplate generators extension
State Machine	State, history, persistence, reactive graph
Studio App	Electron desktop app (renderer, main, preload)
Subagent	Parallel/serial subagent delegation
Syntax Highlighting	Syntect-backed ANSI code coloring
Text Processing	Diff, truncation, HTML→MD, ANSI, JSON parse
Tool System	Tool implementations (bash, edit, read, write, grep…)
TTSR	Time-Traveling Stream Rules regex guardrails
TUI Components	Terminal UI component library (pi-tui)
Universal Config	Multi-tool configuration file discovery
Voice	Voice input extension (Swift/Python)
VS Code Extension	VS Code sidebar, chat participant, RPC client
Web Mode	Web server service layer and RPC bridge
Web UI	Next.js frontend components, pages, hooks
Worktree	Git worktree lifecycle, sync, name generation

---

src/ — Core Application Files

File	System Label(s)	Description
src/app-paths.ts	Config	App directory paths (SF_HOME, sessions, web PID, prefs)
src/app-paths.js	Config	Compiled JS version
src/bundled-extension-paths.ts	Extension Registry	Serializes/parses bundled extension directory paths
src/bundled-resource-path.ts	Loader/Bootstrap, Extension Registry	Resolves bundled raw resource files from package root
src/cli.ts	CLI	Main CLI entry point — arg parsing, mode detection, plugin init
src/cli-web-branch.ts	CLI, Web Mode	Web CLI branch; session dir resolution, legacy migration
src/extension-discovery.ts	Extension Registry	Discovers extension entry points from FS and package.json
src/extension-registry.ts	Extension Registry	Extension manifests, registry persistence, enable/disable
src/headless-answers.ts	Headless Mode	Pre-supply answers to extension UI requests in headless
src/headless-context.ts	Headless Mode	Context loading from stdin/files; project bootstrapping
src/headless-events.ts	Headless Mode	Event classification, terminal detection, idle timeouts
src/headless-query.ts	Headless Mode, CLI	Read-only snapshot query (state, dispatch preview, costs)
src/headless-ui.ts	Headless Mode	Extension UI auto-response, progress formatting
src/headless.ts	Headless Mode	Orchestrator for /sf subcommands without TUI via RPC
src/help-text.ts	CLI	Generates help text for all subcommands
src/loader.ts	Loader/Bootstrap	Fast-path startup, extension discovery/validation, env setup
src/logo.ts	CLI	ASCII logo rendering for welcome screen and loader
src/mcp-server.ts	MCP Server/Client	Native MCP server over stdin/stdout for external AI clients
src/models-resolver.ts	Config, Auth/OAuth	Resolves models.json with fallback from Pi to SF
src/onboarding.ts	Onboarding	First-run wizard — LLM auth, OAuth, API keys, tool setup
src/pi-migration.ts	Config, Auth/OAuth	Migrates provider credentials from Pi auth.json to SF
src/project-sessions.ts	State Machine, CLI	Session-per-project directory paths from project CWD
src/remote-questions-config.ts	Config, Onboarding	Saves remote questions (Discord, Slack, Telegram) config
src/resource-loader.ts	Loader/Bootstrap, Extension Registry	Initializes, syncs, validates bundled resources
src/startup-timings.ts	CLI, Build System	Optional startup timing instrumentation
src/tool-bootstrap.ts	Loader/Bootstrap	Manages fd/rg availability, falls back to built-in
src/update-check.ts	CLI	Checks npm registry for new versions (cached)
src/update-cmd.ts	CLI	Executes npm install to update sf-run package
src/web-mode.ts	Web Mode	Launches/manages web server process (PID tracking, browser)
src/welcome-screen.ts	CLI	Welcome panel — logo, version, model info
src/wizard.ts	Onboarding, Config	Loads env keys from auth.json → hydrates process.env
src/worktree-cli.ts	Worktree, CLI	Worktree lifecycle: create, list, merge, clean, remove
src/worktree-name-gen.ts	Worktree	Generates random worktree names (adjective-verbing-noun)

src/web/ — Web Service Layer

File	System Label(s)	Description
src/web/auto-dashboard-service.ts	Web Mode, Auto Engine	Loads auto-mode dashboard state (active, paused, costs)
src/web/bridge-service.ts	Web Mode, State Machine	Central hub spawning RPC sessions, managing session state
src/web/captures-service.ts	Web Mode	Loads knowledge capture entries via child process bridge
src/web/cleanup-service.ts	Web Mode	Collects SF branches and snapshot refs for cleanup
src/web/cli-entry.ts	Web Mode, CLI	Builds/resolves SF CLI entry points for RPC/interactive
src/web/doctor-service.ts	Web Mode, Doctor/Diagnostics	Runs diagnostics, returns fixer operations
src/web/export-service.ts	Web Mode	Generates exported project reports (markdown/JSON)
src/web/forensics-service.ts	Web Mode, Doctor/Diagnostics	Loads forensic report data (traces, metrics, issues)
src/web/git-summary-service.ts	Web Mode	Provides git branch, commit history, diff summary
src/web/history-service.ts	Web Mode	Loads metrics ledger, aggregates history views
src/web/hooks-service.ts	Web Mode	Manages git hook registration and shell integration
src/web/inspect-service.ts	Web Mode	Detailed inspection of project state and traces
src/web/knowledge-service.ts	Web Mode	Reads and parses KNOWLEDGE.md
src/web/onboarding-service.ts	Web Mode, Onboarding, Auth/OAuth	Manages onboarding state, auth refresh, lock reasons
src/web/project-discovery-service.ts	Web Mode	Discovers and catalogs projects in filesystem
src/web/recovery-diagnostics-service.ts	Web Mode	Recovery suggestions for error states/blockers
src/web/settings-service.ts	Web Mode, Config	Loads preferences, routing config, budget, totals
src/web/skill-health-service.ts	Web Mode, Doctor/Diagnostics	Loads skill health report with capability assessments
src/web/undo-service.ts	Web Mode	Manages undo/snapshot and restoration
src/web/update-service.ts	Web Mode	Checks for and executes application updates
src/web/visualizer-service.ts	Web Mode	Generates visual representations of project state
src/web/web-auth-storage.ts	Web Mode, Auth/OAuth	OAuth and API key credential storage for web mode

---

packages/pi-agent-core/src/ — Agent Core

File	System Label(s)	Description
agent-loop.ts	Agent Core, State Machine	Core agent execution loop — tool calls and LLM interactions
agent.ts	Agent Core	Main Agent class wrapping loop with state management
proxy.ts	Agent Core	Proxy wrapper for agent functionality
types.ts	Agent Core	Type definitions for agent config, context, events
index.ts	Agent Core	Package exports

---

packages/pi-ai/src/ — AI Providers

File	System Label(s)	Description
index.ts	AI Providers	Main export hub for providers and streaming
api-registry.ts	AI Providers	Registry for managing multiple AI provider implementations
models.ts	AI Providers	Model definitions and metadata
models.generated.ts	AI Providers	Auto-generated model list from provider registries
stream.ts	AI Providers	Main streaming interface dispatching to registered providers
types.ts	AI Providers	Core types for models, APIs, streaming options
env-api-keys.ts	AI Providers, Auth/OAuth	Environment variable API key resolution
web-runtime-env-api-keys.ts	AI Providers, Auth/OAuth	Web runtime API key handling
web-runtime-oauth.ts	AI Providers, Auth/OAuth	Web runtime OAuth token management
providers/register-builtins.ts	AI Providers	Registration of built-in provider implementations
providers/anthropic.ts	AI Providers	Anthropic API provider
providers/anthropic-shared.ts	AI Providers	Shared utilities for Anthropic provider variants
providers/anthropic-vertex.ts	AI Providers	Google Vertex AI Anthropic models
providers/amazon-bedrock.ts	AI Providers	AWS Bedrock LLM provider
providers/bedrock-provider.ts	AI Providers	Bedrock-specific streaming logic
providers/google.ts	AI Providers	Google Generative AI provider
providers/google-gemini-cli.ts	AI Providers	Google Gemini CLI authentication provider
providers/google-shared.ts	AI Providers	Shared Google provider utilities
providers/google-vertex.ts	AI Providers	Google Vertex AI provider
providers/mistral.ts	AI Providers	Mistral AI provider
providers/openai-completions.ts	AI Providers	OpenAI legacy completions API
providers/openai-responses.ts	AI Providers	OpenAI responses (chat) API
providers/openai-responses-shared.ts	AI Providers	Shared OpenAI responses utilities
providers/openai-shared.ts	AI Providers	Shared OpenAI utilities
providers/openai-codex-responses.ts	AI Providers	OpenAI Codex-specific response handling
providers/azure-openai-responses.ts	AI Providers	Azure OpenAI responses provider
providers/github-copilot-headers.ts	AI Providers	GitHub Copilot custom header construction
providers/simple-options.ts	AI Providers	Common options builder for simple streaming
providers/transform-messages.ts	AI Providers	Message transformation for provider compatibility
utils/oauth/index.ts	Auth/OAuth	OAuth utilities export hub
utils/oauth/types.ts	Auth/OAuth	OAuth credential and prompt types
utils/oauth/pkce.ts	Auth/OAuth	PKCE flow implementation
utils/oauth/github-copilot.ts	Auth/OAuth	GitHub Copilot OAuth flow
utils/oauth/google-oauth-utils.ts	Auth/OAuth	Shared Google OAuth utilities
utils/oauth/google-gemini-cli.ts	Auth/OAuth	Google Gemini CLI OAuth flow
utils/oauth/google-antigravity.ts	Auth/OAuth	Google Antigravity OAuth implementation
utils/oauth/openai-codex.ts	Auth/OAuth	OpenAI Codex OAuth flow
utils/oauth/anthropic.ts	Auth/OAuth	Anthropic OAuth flow
utils/event-stream.ts	AI Providers	Event stream parsing and handling
utils/hash.ts	AI Providers	Hashing utilities
utils/json-parse.ts	AI Providers	Resilient JSON parsing with recovery
utils/overflow.ts	AI Providers	Token/context overflow detection
utils/sanitize-unicode.ts	AI Providers	Unicode sanitization for API compatibility
utils/validation.ts	AI Providers	Request/response validation schemas
utils/typebox-helpers.ts	AI Providers	TypeBox schema helpers

---

packages/pi-tui/src/ — TUI Components

File	System Label(s)	Description
index.ts	TUI Components	Main TUI export hub
tui.ts	TUI Components	Core TUI renderer and component system
terminal.ts	TUI Components	Low-level terminal I/O and rendering
keys.ts	TUI Components	Keyboard key parsing and matching
keybindings.ts	TUI Components	Keybinding configuration and management
stdin-buffer.ts	TUI Components	Buffered stdin for batch key processing
editor-component.ts	TUI Components	Interface for custom editor implementations
autocomplete.ts	TUI Components	Autocomplete suggestion provider system
fuzzy.ts	TUI Components	Fuzzy matching algorithm
terminal-image.ts	TUI Components	Terminal image protocol (Kitty, iTerm2)
kill-ring.ts	TUI Components	Emacs-style kill ring buffer
undo-stack.ts	TUI Components	Undo/redo stack for editor operations
overlay-layout.ts	TUI Components	Overlay/modal dialog layout system
utils.ts	TUI Components	Text width calculation, ANSI utilities
components/box.ts	TUI Components	Box drawing with borders and styling
components/text.ts	TUI Components	Simple text display component
components/truncated-text.ts	TUI Components	Text with automatic truncation
components/spacer.ts	TUI Components	Vertical/horizontal spacing
components/input.ts	TUI Components	Single-line text input with history
components/loader.ts	TUI Components	Animated loading spinner
components/cancellable-loader.ts	TUI Components	Loading spinner with cancel
components/image.ts	TUI Components	Image display with theme support
components/select-list.ts	TUI Components	List selection UI with keyboard nav
components/settings-list.ts	TUI Components	Settings/preferences list display
components/editor.ts	TUI Components	Full multi-line editor with syntax awareness
components/markdown.ts	TUI Components	Markdown rendering to terminal

---

packages/pi-coding-agent/src/ — Coding Agent

CLI

File	System Label(s)	Description
cli.ts	CLI	Main CLI entry point and argument routing
main.ts	CLI	CLI main entry with mode routing
cli/args.ts	CLI	CLI argument definition and parsing
cli/config-selector.ts	CLI	Interactive configuration selection
cli/file-processor.ts	CLI	File input processing for agent context
cli/list-models.ts	CLI, Model System	Model listing and discovery UI
cli/session-picker.ts	CLI	Session selection interface

Core — Session & State

File	System Label(s)	Description
core/agent-session.ts	Agent Core, State Machine	Core session abstraction, agent lifecycle, persistence
core/session-manager.ts	Session Management	Session file I/O, branch/fork tree management
core/event-bus.ts	Agent Core, Event System	Event publication and subscription
core/messages.ts	State Machine	Message type definitions and constructors
core/settings-manager.ts	Session Management, Config	Session-level settings persistence

Core — Tool System

File	System Label(s)	Description
core/tools/index.ts	Tool System	Tool registry and factory exports
core/tools/bash.ts	Tool System	Bash/shell command execution tool
core/tools/bash-interceptor.ts	Tool System	Bash command interception and filtering
core/tools/edit.ts	Tool System	File editing tool with line ranges
core/tools/edit-diff.ts	Tool System	Edit tool with diff-based operations
core/tools/read.ts	Tool System	File reading tool
core/tools/write.ts	Tool System	File writing tool
core/tools/find.ts	Tool System, File Search	File discovery tool
core/tools/grep.ts	Tool System, File Search	Pattern search tool
core/tools/ls.ts	Tool System	Directory listing tool
core/tools/truncate.ts	Tool System, Text Processing	Output truncation utility
core/tools/hashline.ts	Tool System	Hash-based line identification
core/tools/hashline-read.ts	Tool System	File reading with hash-based line ranges
core/tools/hashline-edit.ts	Tool System	File editing with hash-based line identification
core/tools/path-utils.ts	Tool System	Path normalization and validation
core/bash-executor.ts	Tool System	High-level bash execution with event handling
core/exec.ts	Tool System	Utility functions for command execution

Core — Model Management

File	System Label(s)	Description
core/model-registry.ts	Model System	Model metadata and capability registry
core/model-discovery.ts	Model System	Model discovery from external sources
core/model-resolver.ts	Model System	Model selection and resolution logic
core/models-json-writer.ts	Model System	Model metadata serialization

Core — AI & Context

File	System Label(s)	Description
core/prompt-templates.ts	Agent Core	Template system for prompt construction
core/system-prompt.ts	Agent Core	System prompt building and management
core/retry-handler.ts	AI Providers	Retry logic with exponential backoff
core/fallback-resolver.ts	Model System	Model fallback resolution on API failures
core/slash-commands.ts	Commands	Built-in slash command definitions and handlers

Core — Extensions & Skills

File	System Label(s)	Description
core/extensions/index.ts	Extensions	Extension system exports
core/extensions/types.ts	Extensions	Extension event and context types
core/extensions/loader.ts	Extensions	Extension discovery and loading
core/extensions/runner.ts	Extensions, Event System	Extension event dispatch and execution
core/extensions/wrapper.ts	Extensions, Tool System	Tool wrapping for extension monitoring
core/extensions/project-trust.ts	Extensions, Permissions	Project trust management for local extensions
core/skills.ts	Skills, Tool System	Skill tool registration and management

Core — Compaction

File	System Label(s)	Description
core/compaction-orchestrator.ts	Compaction	Orchestrates session compaction decisions
core/compaction/compaction.ts	Compaction	Context token reduction via summarization
core/compaction/branch-summarization.ts	Compaction	Branch history summarization for context limits
core/compaction/utils.ts	Compaction	Compaction utilities

Core — Configuration & Auth

File	System Label(s)	Description
config.ts	Config	Directory paths and version management
core/sdk.ts	Agent Core	Main SDK factory for creating agent sessions
core/resolve-config-value.ts	Config	Config value resolution from environment/files
core/resource-loader.ts	Config, Loader/Bootstrap	Extensible resource loading (tools, extensions, themes)
core/defaults.ts	Config	Default configuration values
core/constants.ts	Config	Global constants
core/auth-storage.ts	Auth/OAuth, Permissions	OAuth token storage and management
migrations.ts	Config, Migration	Configuration migration and deprecation handling

Core — Artifacts & Export

File	System Label(s)	Description
core/artifact-manager.ts	Agent Core	Artifact file management and metadata
core/blob-store.ts	Agent Core	Binary data storage for images and attachments
core/export-html/index.ts	Web Mode	Session export to HTML
core/export-html/ansi-to-html.ts	Web Mode	ANSI code to HTML conversion
core/export-html/tool-renderer.ts	Web Mode	HTML rendering for tool calls/results

Core — LSP

File	System Label(s)	Description
core/lsp/index.ts	LSP	LSP integration exports
core/lsp/client.ts	LSP	LSP client implementation
core/lsp/lspmux.ts	LSP	LSP server multiplexing
core/lsp/config.ts	LSP	LSP server configuration
core/lsp/edits.ts	LSP	LSP-based code editing operations
core/lsp/helpers.ts	LSP	LSP utility functions
core/lsp/types.ts	LSP	LSP type definitions
core/lsp/utils.ts	LSP	LSP utilities

Core — Utilities

File	System Label(s)	Description
core/fs-utils.ts	Tool System	File system utilities (atomic writes, temp files)
core/lock-utils.ts	Tool System	File locking for concurrent access
core/timings.ts	Build System	Performance timing measurement
core/diagnostics.ts	Doctor/Diagnostics	Diagnostic information collection
core/discovery-cache.ts	Model System	Model discovery result caching
core/keybindings.ts	TUI Components	Keybinding definitions
core/footer-data-provider.ts	TUI Components	Footer information provider
core/index.ts	Agent Core	Core module exports
index.ts	Agent Core	Package exports
utils/clipboard.ts	Tool System	Clipboard read/write
utils/clipboard-native.ts	Tool System	Native clipboard implementation
utils/clipboard-image.ts	Tool System	Clipboard image support
utils/error.ts	Agent Core	Error message extraction/formatting
utils/frontmatter.ts	Config	YAML frontmatter parsing
utils/git.ts	Tool System	Git information and utilities
utils/image-convert.ts	Image Processing	Image format conversion
utils/image-resize.ts	Image Processing	Image resizing and optimization
utils/mime.ts	Tool System	MIME type detection
utils/path-display.ts	TUI Components	Path formatting for display
utils/photon.ts	Agent Core	Photon scripting runtime support
utils/shell.ts	Tool System	Shell detection and execution
utils/changelog.ts	CLI	Changelog parsing
utils/sleep.ts	Agent Core	Async sleep/delay utility
utils/tools-manager.ts	Tool System	Tool discovery and management
package-manager.ts	Build System	npm/yarn/pnpm/bun abstraction

Modes

File	System Label(s)	Description
modes/index.ts	Modes	Mode system exports
modes/print-mode.ts	Modes	Non-interactive print mode
modes/rpc/rpc-mode.ts	Modes, MCP Server/Client	RPC server mode for remote access
modes/rpc/rpc-client.ts	Modes, MCP Server/Client	RPC client for remote agent interaction
modes/rpc/rpc-types.ts	Modes, MCP Server/Client	RPC protocol type definitions
modes/rpc/jsonl.ts	Modes	JSONL serialization for RPC
modes/rpc/remote-terminal.ts	Modes	Remote terminal output handling
modes/shared/command-context-actions.ts	Modes, Commands	Shared command context utilities
modes/interactive/interactive-mode.ts	Modes, TUI Components	Main interactive TUI mode orchestration
modes/interactive/interactive-mode-state.ts	Modes, TUI Components, State Machine	Interactive mode state management
modes/interactive/slash-command-handlers.ts	Modes, Commands	Interactive mode slash command handlers
modes/interactive/theme/theme.ts	TUI Components	Theme system and hot reloading
modes/interactive/theme/themes.ts	TUI Components	Built-in theme definitions
modes/interactive/utils/shorten-path.ts	TUI Components	Path shortening for display
modes/interactive/controllers/chat-controller.ts	Modes, TUI Components	Chat input and message submission
modes/interactive/controllers/input-controller.ts	Modes, TUI Components	Input handling and routing
modes/interactive/controllers/model-controller.ts	Modes, TUI Components, Model System	Model/provider/thinking configuration
modes/interactive/controllers/extension-ui-controller.ts	Modes, TUI Components, Extensions	Extension UI event handling

Modes — Interactive Components

File	System Label(s)	Description
components/index.ts	TUI Components	Interactive mode component exports
components/armin.ts	TUI Components	Assistant message rendering
components/assistant-message.ts	TUI Components	Assistant message display
components/user-message.ts	TUI Components	User message display
components/user-message-selector.ts	TUI Components	User message editing selector
components/bash-execution.ts	TUI Components, Tool System	Bash execution result display
components/tool-execution.ts	TUI Components, Tool System	Tool call and result display
components/custom-message.ts	TUI Components	Custom message type display
components/custom-editor.ts	TUI Components	Custom editor integration
components/skill-invocation-message.ts	TUI Components, Skills	Skill invocation display
components/branch-summary-message.ts	TUI Components, Compaction	Branch summary display
components/compaction-summary-message.ts	TUI Components, Compaction	Compaction summary display
components/diff.ts	TUI Components, Text Processing	Diff display component
components/tree-render-utils.ts	TUI Components, Session Management	Session tree rendering utilities
components/tree-selector.ts	TUI Components, Session Management	Session tree navigation UI
components/session-selector.ts	TUI Components, Session Management	Session selection UI
components/session-selector-search.ts	TUI Components, Session Management	Session search UI
components/model-selector.ts	TUI Components, Model System	Model selection UI
components/scoped-models-selector.ts	TUI Components, Model System	Scoped model selection
components/thinking-selector.ts	TUI Components, Model System	Thinking level selection
components/provider-manager.ts	TUI Components, AI Providers	Provider configuration UI
components/oauth-selector.ts	TUI Components, Auth/OAuth	OAuth provider selection/login
components/login-dialog.ts	TUI Components, Auth/OAuth	OAuth login dialog
components/theme-selector.ts	TUI Components	Theme selection UI
components/config-selector.ts	TUI Components, Config	Configuration selection UI
components/extension-selector.ts	TUI Components, Extensions	Extension selection UI
components/extension-editor.ts	TUI Components, Extensions	Extension code editor
components/extension-input.ts	TUI Components, Extensions	Extension input handling
components/settings-selector.ts	TUI Components, Config	Settings/preferences UI
components/show-images-selector.ts	TUI Components, Config	Image display toggle
components/bordered-loader.ts	TUI Components	Loading spinner with border
components/countdown-timer.ts	TUI Components	Countdown timer display
components/dynamic-border.ts	TUI Components	Dynamic border drawing
components/keybinding-hints.ts	TUI Components	Keybinding help display
components/footer.ts	TUI Components	Footer information display
components/daxnuts.ts	TUI Components	Special rendering effect
components/visual-truncate.ts	TUI Components	Visual text truncation

Resources — Memory Extension

File	System Label(s)	Description
resources/extensions/memory/index.ts	Memory Extension	Memory extension index and setup
resources/extensions/memory/pipeline.ts	Memory Extension	Memory processing pipeline
resources/extensions/memory/storage.ts	Memory Extension	Memory persistence storage

---

src/resources/extensions/ — Extension Subsystems

SF Extension (Core Workflow Engine)

File	System Label(s)	Description
sf/index.ts	SF Workflow	Main SF extension bootstrap and registration
sf/auto.ts	Auto Engine	Automatic workflow execution and loop management
sf/auto-dashboard.ts	Auto Engine, Web Mode	Real-time dashboard for auto-run progress
sf/auto-worktree.ts	Auto Engine, Worktree	Automatic worktree creation and branch management
sf/auto-recovery.ts	Auto Engine	Recovery for crashed/stalled workflows
sf/auto-start.ts	Auto Engine	Initialization sequence for automatic execution
sf/auto-worktree-sync.ts	Auto Engine, Worktree	State sync between worktrees and main
sf/auto-model-selection.ts	Auto Engine, Model System	Intelligent LLM model routing
sf/auto-direct-dispatch.ts	Auto Engine	Direct command dispatching without planning
sf/auto-dispatch.ts	Auto Engine	Task queueing and priority-based dispatch
sf/auto-timeout-recovery.ts	Auto Engine	Timeout handling and recovery
sf/auto-post-unit.ts	Auto Engine	Post-unit milestone completion processing
sf/auto-unit-closeout.ts	Auto Engine	Unit finalization and archiving
sf/auto-verification.ts	Auto Engine	Post-execution verification
sf/auto-timers.ts	Auto Engine	Timeout and deadline management
sf/auto-loop.ts	Auto Engine, State Machine	Execution loop state and cycle management
sf/auto-supervisor.ts	Auto Engine	Supervision and oversight of autonomous runs
sf/auto-budget.ts	Auto Engine	Token/cost budgeting and tracking
sf/auto-observability.ts	Auto Engine	Observability hooks and telemetry
sf/auto-tool-tracking.ts	Auto Engine	Tool usage instrumentation
sf/doctor.ts	Doctor/Diagnostics	Health check and system diagnostics
sf/doctor-checks.ts	Doctor/Diagnostics	Individual diagnostic checks
sf/doctor-providers.ts	Doctor/Diagnostics	Diagnostic data source providers
sf/doctor-format.ts	Doctor/Diagnostics	Diagnostic output formatting
sf/state.ts	State Machine	Milestone and workflow state management
sf/history.ts	State Machine	State history and versioning
sf/json-persistence.ts	State Machine	JSON-based persistence layer
sf/memory-store.ts	State Machine	In-memory state storage
sf/reactive-graph.ts	State Machine	Reactive dependency graph for state
sf/routing-history.ts	State Machine	History of routing decisions
sf/cache.ts	State Machine	Caching layer for performance
sf/model-router.ts	Model System	LLM model selection and routing logic
sf/worktree.ts	Worktree	Worktree creation and management
sf/worktree-manager.ts	Worktree	Higher-level worktree orchestration
sf/worktree-resolver.ts	Worktree	Worktree path and reference resolution
sf/unit-runtime.ts	Auto Engine	Unit-level execution runtime
sf/activity-log.ts	SF Workflow	Activity tracking and logging
sf/debug-logger.ts	SF Workflow	Debug output and verbose logging
sf/commands.ts	Commands	Main command dispatcher
sf/commands-handlers.ts	Commands	Command-specific handlers
sf/commands-bootstrap.ts	Commands	Bootstrap and initialization commands
sf/commands-config.ts	Commands, Config	Configuration management commands
sf/commands-extensions.ts	Commands, Extensions	Extension discovery and management
sf/commands-inspect.ts	Commands, Doctor/Diagnostics	Database and state inspection tools
sf/commands-logs.ts	Commands	Log viewing and filtering
sf/commands-workflow-templates.ts	Commands, SF Workflow	Workflow template management
sf/commands-cmux.ts	Commands, CMux	Tmux/cmux integration commands
sf/exit-command.ts	Commands	Exit and cleanup commands
sf/undo.ts	Commands	Undo and rollback functionality
sf/kill.ts	Commands	Process termination and cleanup
sf/worktree-command.ts	Commands, Worktree	Worktree subcommands
sf/namespaced-resolver.ts	SF Workflow	Namespace and scoped resource resolution
sf/error-utils.ts	SF Workflow	Error handling and formatting
sf/errors.ts	SF Workflow	Error type definitions
sf/diff-context.ts	SF Workflow	Diff-based context extraction
sf/memory-extractor.ts	SF Workflow	Memory and context extraction from state
sf/structured-data-formatter.ts	SF Workflow	Structured output formatting
sf/export-html.ts	SF Workflow	HTML export of milestone reports
sf/reports.ts	SF Workflow	Report generation and summaries
sf/notifications.ts	SF Workflow	User notification and messaging
sf/triage-ui.ts	SF Workflow	Triage interface for issue categorization
sf/guided-flow.ts	SF Workflow	User-guided workflow orchestration
sf/env-utils.ts	SF Workflow	Environment variable utilities
sf/git-constants.ts	SF Workflow	Git-related constants and paths
sf/milestone-id-utils.ts	SF Workflow	Milestone ID generation and parsing
sf/resource-version.ts	SF Workflow	Resource versioning helpers
sf/atomic-write.ts	SF Workflow	Atomic file write operations
sf/captures.ts	SF Workflow	Artifact capture and storage
sf/changelog.ts	SF Workflow	Changelog generation
sf/claude-import.ts	SF Workflow	Claude API/resource importing
sf/collision-diagnostics.ts	Doctor/Diagnostics	Collision detection and diagnostics
sf/prompt-loader.ts	SF Workflow	Prompt template loading
sf/file-watcher.ts	SF Workflow	File system change monitoring
sf/parallel-eligibility.ts	SF Workflow	Parallel execution eligibility checks
sf/plugin-importer.ts	SF Workflow, Extensions	Custom plugin/extension importing
sf/verification-gate.ts	SF Workflow	Pre-execution verification checks
sf/preference-models.ts	Config, Model System	Model preference configuration
sf/preferences-skills.ts	Config, Skills	Skill preference configuration
sf/post-unit-hooks.ts	SF Workflow	Post-unit execution hooks
sf/skill-telemetry.ts	Skills	Skill usage and performance telemetry
sf/bootstrap/*	SF Workflow, Loader/Bootstrap	Extension initialization and hook registration
sf/auto/*	Auto Engine	Auto-execution engine components
sf/commands/*	Commands	Command routing and handling
sf/templates/*	SF Workflow	Output templates and formatters
sf/prompts/*	SF Workflow	System prompts and instructions
sf/workflow-templates/*	SF Workflow	Workflow starter templates and registry
sf/skills/*	Skills	Integrated skill configurations
sf/migrate/*	Migration	Data migration and upgrade tools

Other Extensions

File	System Label(s)	Description
async-jobs/index.ts	Async Jobs	Background bash command execution extension
async-jobs/job-manager.ts	Async Jobs	Background job lifecycle management
async-jobs/async-bash-tool.ts	Async Jobs, Tool System	Tool for spawning background bash processes
async-jobs/await-tool.ts	Async Jobs, Tool System	Tool for waiting on job completion
async-jobs/cancel-job-tool.ts	Async Jobs, Tool System	Tool for cancelling background jobs
bg-shell/index.ts	Bg Shell	Interactive background process management extension
bg-shell/bg-shell-tool.ts	Bg Shell, Tool System	Tool for spawning background processes
bg-shell/bg-shell-command.ts	Bg Shell, Commands	Command handler for bg subcommands
bg-shell/bg-shell-lifecycle.ts	Bg Shell	Process lifecycle and state management
bg-shell/process-manager.ts	Bg Shell	Core process management implementation
bg-shell/readiness-detector.ts	Bg Shell	Startup readiness detection
bg-shell/interaction.ts	Bg Shell	Interactive process communication
bg-shell/output-formatter.ts	Bg Shell	Process output formatting
bg-shell/overlay.ts	Bg Shell, TUI Components	Terminal overlay for process monitoring
browser-tools/index.ts	Browser Tools	Playwright-based browser automation extension
browser-tools/core.ts	Browser Tools	Core Playwright instance management
browser-tools/lifecycle.ts	Browser Tools	Browser session lifecycle
browser-tools/capture.ts	Browser Tools	Screenshot and media capture
browser-tools/settle.ts	Browser Tools	Page settlement and readiness detection
browser-tools/refs.ts	Browser Tools	Reference-based element selection
browser-tools/state.ts	Browser Tools, State Machine	Browser state management
browser-tools/tools/navigation.ts	Browser Tools, Tool System	Navigation and page loading tool
browser-tools/tools/interaction.ts	Browser Tools, Tool System	Element interaction tool (click, type)
browser-tools/tools/screenshot.ts	Browser Tools, Tool System	Screenshot and visual capture tool
browser-tools/tools/inspection.ts	Browser Tools, Tool System	Page inspection tool
browser-tools/tools/session.ts	Browser Tools, Tool System	Session management and cookies tool
browser-tools/tools/pages.ts	Browser Tools, Tool System	Multi-page management tool
browser-tools/tools/forms.ts	Browser Tools, Tool System	Form filling and submission tool
browser-tools/tools/wait.ts	Browser Tools, Tool System	Wait conditions and polling tool
browser-tools/tools/assertions.ts	Browser Tools, Tool System	Visual and content assertions tool
browser-tools/tools/verify.ts	Browser Tools, Tool System	Verification checks tool
browser-tools/tools/extract.ts	Browser Tools, Tool System	Data extraction tool
browser-tools/tools/pdf.ts	Browser Tools, Tool System	PDF export/generation tool
browser-tools/tools/state-persistence.ts	Browser Tools, Tool System	State save/restore tool
browser-tools/tools/network-mock.ts	Browser Tools, Tool System	Network mocking/interception tool
browser-tools/tools/device.ts	Browser Tools, Tool System	Device emulation tool
browser-tools/tools/visual-diff.ts	Browser Tools, Tool System	Visual regression testing tool
browser-tools/tools/zoom.ts	Browser Tools, Tool System	Zoom and viewport manipulation tool
browser-tools/tools/codegen.ts	Browser Tools, Tool System	Test code generation tool
browser-tools/tools/action-cache.ts	Browser Tools	Action caching and replay
context7/index.ts	Context7, Tool System	Library documentation fetching extension
google-search/index.ts	Google Search, Tool System	Web search via Google API
search-the-web/index.ts	Search the Web	Brave/Jina/Tavily-based web search extension
search-the-web/provider.ts	Search the Web	Search provider abstraction
search-the-web/native-search.ts	Search the Web	Native Brave search implementation
search-the-web/tavily.ts	Search the Web	Tavily search provider
search-the-web/tool-search.ts	Search the Web, Tool System	Search tool implementation
search-the-web/tool-fetch-page.ts	Search the Web, Tool System	Page fetching tool
search-the-web/cache.ts	Search the Web	Search result caching
remote-questions/index.ts	Remote Questions	Remote question routing extension
remote-questions/manager.ts	Remote Questions	Question lifecycle management
remote-questions/slack-adapter.ts	Remote Questions	Slack messaging adapter
remote-questions/discord-adapter.ts	Remote Questions	Discord messaging adapter
remote-questions/telegram-adapter.ts	Remote Questions	Telegram messaging adapter
mcp-client/index.ts	MCP Server/Client	Model Context Protocol client integration
subagent/index.ts	Subagent, Agent Core	Parallel/serial subagent delegation extension
subagent/agents.ts	Subagent, Agent Core	Agent registry and discovery
subagent/isolation.ts	Subagent	Execution isolation and sandboxing
subagent/worker-registry.ts	Subagent	Worker process management
slash-commands/index.ts	Slash Commands, Commands	Command boilerplate generators extension
slash-commands/create-slash-command.ts	Slash Commands	Generator for new slash command scaffolding
slash-commands/create-extension.ts	Slash Commands, Extensions	Generator for new extension scaffolding
universal-config/index.ts	Universal Config	Multi-tool configuration file discovery
universal-config/discovery.ts	Universal Config	Configuration file discovery
universal-config/scanners.ts	Universal Config	Tool-specific config scanners
ttsr/index.ts	TTSR	TTSR regex engine — streaming output guardrails
ttsr/ttsr-manager.ts	TTSR	Streaming rule manager
ttsr/rule-loader.ts	TTSR	Rule loading and parsing
voice/index.ts	Voice	Voice input mode extension
voice/speech-recognizer.swift	Voice	macOS Swift speech recognizer
voice/speech-recognizer.py	Voice	Linux/Windows Python speech recognizer
cmux/index.ts	CMux	Tmux/multiplexer session management
mac-tools/index.ts	Mac Tools	macOS-specific utilities extension
mac-tools/swift-cli/Sources/main.swift	Mac Tools	macOS native tools Swift implementation
aws-auth/index.ts	Auth/OAuth	AWS authentication and credential handling
shared/ui.ts	TUI Components	Generic UI components and utilities
shared/tui.ts	TUI Components	Terminal UI helpers
shared/interview-ui.ts	TUI Components	Interview-style questionnaire UI
shared/confirm-ui.ts	TUI Components	Confirmation dialog UI
shared/terminal.ts	TUI Components	Terminal operations and formatting
shared/format-utils.ts	SF Workflow	String formatting utilities
shared/sanitize.ts	SF Workflow	Input sanitization
shared/frontmatter.ts	Config	YAML frontmatter parsing

src/resources/agents/

File	System Label(s)	Description
javascript-pro.md	Subagent	JavaScript specialist agent definition
typescript-pro.md	Subagent	TypeScript specialist agent definition
worker.md	Subagent	Generic worker agent definition
researcher.md	Subagent	Research and exploration agent definition
scout.md	Subagent	Scout/pathfinding agent definition

src/resources/skills/

Skill Directory	System Label(s)	Description
react-best-practices/	Skills	React development patterns (62 files)
userinterface-wiki/	Skills	UI/UX guidelines and component reference (155 files)
create-skill/	Skills	Skill creation scaffolding and templates (25 files)
create-sf-extension/	Skills, Extensions	SF extension scaffolding (22 files)
code-optimizer/	Skills	Performance optimization techniques (16 files)
agent-browser/	Skills, Browser Tools	Browser automation guidance (11 files)
github-workflows/	Skills	GitHub Actions workflow patterns (10 files)
debug-like-expert/	Skills	Advanced debugging techniques (6 files)
make-interfaces-feel-better/	Skills	UI/UX improvement patterns (5 files)
accessibility/	Skills	WCAG and accessibility standards
core-web-vitals/	Skills	Web performance metrics guidance
web-quality-audit/	Skills	Quality audit procedures
best-practices/	Skills	General development best practices
frontend-design/	Skills	Frontend design principles
lint/	Skills	Code linting standards
review/	Skills	Code review guidelines
test/	Skills	Testing strategies and patterns
web-design-guidelines/	Skills	Web design principles

---

web/ — Web Frontend (Next.js)

App Shell & Navigation

File	System Label(s)	Description
web/app/layout.tsx	Web UI	Root Next.js layout with theme provider and font
web/app/page.tsx	Web UI	Entry page loading GSDAppShell
web/components/sf/app-shell.tsx	Web UI	Main app shell — sidebar, panels, terminal, commands
web/components/sf/sidebar.tsx	Web UI	Multi-panel sidebar with milestone explorer
web/components/sf/status-bar.tsx	Web UI	Status bar with workspace state and metrics

Main Views

File	System Label(s)	Description
web/components/sf/dashboard.tsx	Web UI	Dashboard with workflow actions and metrics
web/components/sf/chat-mode.tsx	Web UI	Chat interface for agent interaction
web/components/sf/projects-view.tsx	Web UI	Project browser and selector
web/components/sf/files-view.tsx	Web UI	File browser and explorer
web/components/sf/activity-view.tsx	Web UI	Activity log and history view
web/components/sf/roadmap.tsx	Web UI, SF Workflow	Milestone roadmap visualization
web/components/sf/visualizer-view.tsx	Web UI, Doctor/Diagnostics	Workflow visualization
web/components/sf/project-welcome.tsx	Web UI	Welcome screen for new projects
web/components/sf/knowledge-captures-panel.tsx	Web UI	Knowledge and capture management

Terminal

File	System Label(s)	Description
web/components/sf/terminal.tsx	Web UI	Terminal widget with input mode handling
web/components/sf/shell-terminal.tsx	Web UI	Shell terminal with PTY integration
web/components/sf/main-session-terminal.tsx	Web UI	Main session terminal display
web/components/sf/dual-terminal.tsx	Web UI	Side-by-side terminal layout

Commands & Dialogs

File	System Label(s)	Description
web/components/sf/command-surface.tsx	Web UI, Commands	Command palette and slash command dispatcher
web/components/sf/remaining-command-panels.tsx	Web UI, Commands	History, undo, export, cleanup panels
web/components/sf/diagnostics-panels.tsx	Web UI, Doctor/Diagnostics	Doctor, forensics, skill health panels
web/components/sf/settings-panels.tsx	Web UI, Config	Settings and preferences panels
web/components/sf/guided-dialog.tsx	Web UI	Generic guided dialog component
web/components/sf/update-banner.tsx	Web UI	Update notification banner
web/components/sf/scope-badge.tsx	Web UI	Scope badge indicator
web/components/sf/loading-skeletons.tsx	Web UI	Loading skeleton placeholders
web/components/sf/code-editor.tsx	Web UI	Code editor display component
web/components/sf/file-content-viewer.tsx	Web UI	File content viewer and previewer
web/components/sf/focused-panel.tsx	Web UI	Focused panel layout component

Onboarding

File	System Label(s)	Description
web/components/sf/onboarding-gate.tsx	Web UI, Onboarding	Gate and orchestration for onboarding flow
web/components/sf/onboarding/step-welcome.tsx	Web UI, Onboarding	Welcome step
web/components/sf/onboarding/step-mode.tsx	Web UI, Onboarding	User mode selection step
web/components/sf/onboarding/step-provider.tsx	Web UI, Onboarding	LLM provider selection step
web/components/sf/onboarding/step-authenticate.tsx	Web UI, Onboarding, Auth/OAuth	Authentication step
web/components/sf/onboarding/step-dev-root.tsx	Web UI, Onboarding	Dev root directory selection step
web/components/sf/onboarding/step-project.tsx	Web UI, Onboarding	Project selection step
web/components/sf/onboarding/step-remote.tsx	Web UI, Onboarding	Remote configuration step
web/components/sf/onboarding/step-optional.tsx	Web UI, Onboarding	Optional settings step
web/components/sf/onboarding/step-ready.tsx	Web UI, Onboarding	Ready confirmation step
web/components/sf/onboarding/wizard-stepper.tsx	Web UI, Onboarding	Stepper progress indicator

API Routes

File	System Label(s)	Description
web/app/api/boot/route.ts	API Routes, State Machine	Initial boot payload with project/workspace state
web/app/api/session/manage/route.ts	API Routes, Session Management	Session rename and management
web/app/api/session/browser/route.ts	API Routes, Session Management	Session browser listing
web/app/api/session/command/route.ts	API Routes, Session Management	Session command execution
web/app/api/session/events/route.ts	API Routes, Session Management	Session event streaming (SSE)
web/app/api/terminal/stream/route.ts	API Routes	PTY output streaming via SSE
web/app/api/terminal/input/route.ts	API Routes	Terminal input submission
web/app/api/terminal/resize/route.ts	API Routes	Terminal resize
web/app/api/terminal/sessions/route.ts	API Routes	Terminal session management
web/app/api/terminal/upload/route.ts	API Routes	File upload for terminal
web/app/api/bridge-terminal/stream/route.ts	API Routes, Web Mode	Bridge terminal output streaming
web/app/api/bridge-terminal/input/route.ts	API Routes, Web Mode	Bridge terminal input
web/app/api/bridge-terminal/resize/route.ts	API Routes, Web Mode	Bridge terminal resize
web/app/api/projects/route.ts	API Routes	Project discovery and listing
web/app/api/live-state/route.ts	API Routes, State Machine	Live workspace state updates
web/app/api/steer/route.ts	API Routes, Commands	Steering endpoint for agent direction
web/app/api/history/route.ts	API Routes, State Machine	History and metrics
web/app/api/undo/route.ts	API Routes, Commands	Undo operation
web/app/api/cleanup/route.ts	API Routes, Commands	Cleanup operation
web/app/api/export-data/route.ts	API Routes, Commands	Data export
web/app/api/knowledge/route.ts	API Routes, SF Workflow	Knowledge base
web/app/api/hooks/route.ts	API Routes, SF Workflow	Git hooks management
web/app/api/inspect/route.ts	API Routes, Doctor/Diagnostics	Inspection and analysis
web/app/api/doctor/route.ts	API Routes, Doctor/Diagnostics	Doctor diagnostic tool
web/app/api/forensics/route.ts	API Routes, Doctor/Diagnostics	Forensics analysis
web/app/api/skill-health/route.ts	API Routes, Doctor/Diagnostics	Skill health check
web/app/api/visualizer/route.ts	API Routes, Doctor/Diagnostics	Workflow visualization
web/app/api/preferences/route.ts	API Routes, Config	User preferences
web/app/api/settings-data/route.ts	API Routes, Config	Settings data
web/app/api/dev-mode/route.ts	API Routes, Config	Development mode toggle
web/app/api/captures/route.ts	API Routes, SF Workflow	Knowledge captures
web/app/api/browse-directories/route.ts	API Routes	Directory browsing
web/app/api/files/route.ts	API Routes, Tool System	File system access
web/app/api/git/route.ts	API Routes, Tool System	Git operations
web/app/api/onboarding/route.ts	API Routes, Onboarding	Onboarding data
web/app/api/recovery/route.ts	API Routes, Doctor/Diagnostics	Recovery operations
web/app/api/remote-questions/route.ts	API Routes, Remote Questions	Remote question handling
web/app/api/shutdown/route.ts	API Routes	Graceful shutdown
web/app/api/update/route.ts	API Routes, CLI	Update check

Library & State

File	System Label(s)	Description
web/lib/auth.ts	Auth/OAuth	Client-side auth token management from URL fragment
web/lib/sf-workspace-store.tsx	State Machine	Global workspace state store with external store
web/lib/project-store-manager.tsx	State Machine	Multi-project store manager with SSE lifecycle
web/lib/shutdown-gate.ts	State Machine	Graceful shutdown coordination
web/lib/browser-slash-command-dispatch.ts	Commands	Slash command dispatch
web/lib/workflow-actions.ts	SF Workflow	Primary workflow action derivation logic
web/lib/workflow-action-execution.ts	SF Workflow	Workflow action execution handler
web/lib/command-surface-contract.ts	Commands	Command surface request/response contract types
web/lib/pty-manager.ts	Web UI	Server-side PTY spawning and session management
web/lib/pty-chat-parser.ts	Web UI	PTY output parsing for chat display
web/lib/remaining-command-types.ts	Web UI	Browser-safe types for command surfaces
web/lib/knowledge-captures-types.ts	SF Workflow	Knowledge entry and captures types
web/lib/diagnostics-types.ts	Doctor/Diagnostics	Diagnostics panel types
web/lib/settings-types.ts	Config	Settings and preferences types
web/lib/visualizer-types.ts	Doctor/Diagnostics	Workflow visualizer types
web/lib/session-browser-contract.ts	Session Management	Session browser contract types
web/lib/git-summary-contract.ts	Tool System	Git summary contract types
web/lib/utils.ts	Web UI	Common utility functions
web/lib/project-url.ts	Web UI	Project URL parsing and construction
web/lib/workspace-status.ts	Web UI, State Machine	Workspace status derivation
web/lib/image-utils.ts	Image Processing	Image handling and processing utilities
web/lib/use-editor-font-size.ts	Web UI	Editor font size preference hook
web/lib/use-terminal-font-size.ts	Web UI	Terminal font size preference hook
web/lib/use-user-mode.ts	Web UI	User mode hook
web/hooks/use-mobile.ts	Web UI	Mobile viewport detection hook
web/hooks/use-toast.ts	Web UI	Toast notification hook
web/components/theme-provider.tsx	Web UI	Theme provider for dark/light modes
web/components/ui/* (50+ files)	Web UI	Shadcn/ui base component library

---

vscode-extension/ — VS Code Extension

File	System Label(s)	Description
vscode-extension/src/extension.ts	VS Code Extension	Extension activation, client management, command registration
vscode-extension/src/sf-client.ts	VS Code Extension, MCP Server/Client	RPC client for SF agent communication
vscode-extension/src/chat-participant.ts	VS Code Extension	Chat participant for @sf command
vscode-extension/src/sidebar.ts	VS Code Extension	Sidebar webview provider with status display

---

studio/ — Electron Desktop App

File	System Label(s)	Description
studio/electron.vite.config.ts	Studio App, Build System	Electron Vite build configuration
studio/src/main/index.ts	Studio App	Electron main process window creation
studio/src/preload/index.ts	Studio App	Context isolation preload for IPC bridge
studio/src/preload/index.d.ts	Studio App	Preload bridge type definitions
studio/src/renderer/src/main.tsx	Studio App	React renderer entry point
studio/src/renderer/src/App.tsx	Studio App	Main app component
studio/src/renderer/src/lib/theme/tokens.ts	Studio App	Design tokens (colors, fonts, sizes)

---

native/ — Rust Engine

File	System Label(s)	Description
native/crates/engine/src/lib.rs	Native/Rust Tools	N-API entry point exposing all Rust modules
native/crates/engine/src/grep.rs	File Search, Native/Rust Tools	Ripgrep-backed regex search with context/globbing
native/crates/engine/src/glob.rs	File Search, Native/Rust Tools	Glob-pattern FS discovery with gitignore + scan cache
native/crates/engine/src/fd.rs	File Search, Native/Rust Tools	Fuzzy file discovery for autocomplete/@-mentions
native/crates/engine/src/highlight.rs	Syntax Highlighting, Native/Rust Tools	Syntect-backed ANSI syntax highlighting
native/crates/engine/src/ast.rs	AST, Native/Rust Tools	Linker shim for AST N-API registrations
native/crates/engine/src/diff.rs	Text Processing, Native/Rust Tools	Fuzzy matching, Unicode normalization, unified diffs
native/crates/engine/src/image.rs	Image Processing, Native/Rust Tools	Image decode/encode and resize
native/crates/engine/src/html.rs	Text Processing, Native/Rust Tools	HTML to Markdown conversion
native/crates/engine/src/text.rs	Text Processing, Native/Rust Tools	ANSI-aware text measurement and slicing
native/crates/engine/src/truncate.rs	Text Processing, Native/Rust Tools	Line-boundary-aware output truncation
native/crates/engine/src/ps.rs	Native/Rust Tools	Cross-platform process tree management
native/crates/engine/src/clipboard.rs	Native/Rust Tools	Clipboard read/write for text and images
native/crates/engine/src/json_parse.rs	Text Processing, Native/Rust Tools	Streaming JSON parser with partial recovery
native/crates/engine/src/sf_parser.rs	SF Workflow, Native/Rust Tools	.sf/ directory file parser (markdown, frontmatter)
native/crates/engine/src/ttsr.rs	TTSR, Native/Rust Tools	TTSR regex engine with compiled RegexSet
native/crates/engine/src/stream_process.rs	Text Processing, Native/Rust Tools	Bash stream processor (UTF-8, ANSI strip, binary)
native/crates/engine/src/xxhash.rs	Native/Rust Tools	xxHash32 for hashline edit tool
native/crates/engine/src/git.rs	Native/Rust Tools	Native git operations via libgit2
native/crates/engine/src/fs_cache.rs	File Search, Native/Rust Tools	TTL-based FS scan cache with explicit invalidation
native/crates/engine/src/glob_util.rs	File Search, Native/Rust Tools	Shared glob-pattern helpers
native/crates/engine/src/task.rs	Native/Rust Tools	Blocking work on libuv thread pool with cancellation
native/crates/engine/build.rs	Build System	Cargo build script for napi-build compilation
native/crates/grep/src/lib.rs	File Search, Native/Rust Tools	Ripgrep search library (in-memory and on-disk)
native/crates/ast/src/lib.rs	AST, Native/Rust Tools	AST-aware structural search and rewrite engine
native/crates/ast/src/ast.rs	AST, Native/Rust Tools	ast-grep integration for structural code search
native/crates/ast/src/language/mod.rs	AST, Native/Rust Tools	Vendored language defs and tree-sitter bindings
native/crates/ast/src/language/parsers.rs	AST, Native/Rust Tools	Pre-compiled tree-sitter parsers (50+ languages)

packages/native/src/ — Node.js Rust Bindings

File	System Label(s)	Description
packages/native/src/native.ts	Native/Rust Tools, Node.js Bindings	Native addon loader with platform fallback
packages/native/src/grep/index.ts	File Search, Node.js Bindings	Ripgrep wrapper for regex search
packages/native/src/fd/index.ts	File Search, Node.js Bindings	Fuzzy file discovery wrapper
packages/native/src/highlight/index.ts	Syntax Highlighting, Node.js Bindings	Syntax highlighting wrapper
packages/native/src/image/index.ts	Image Processing, Node.js Bindings	Image processing wrapper
packages/native/src/html/index.ts	Text Processing, Node.js Bindings	HTML to Markdown wrapper
packages/native/src/diff/index.ts	Text Processing, Node.js Bindings	Text diffing wrapper
packages/native/src/ps/index.ts	Native/Rust Tools, Node.js Bindings	Process tree management wrapper
packages/native/src/truncate/index.ts	Text Processing, Node.js Bindings	Output truncation wrapper
packages/native/src/json-parse/index.ts	Text Processing, Node.js Bindings	JSON parsing wrapper
packages/native/src/stream-process/index.ts	Text Processing, Node.js Bindings	Stream processing wrapper
packages/native/src/ttsr/index.ts	TTSR, Node.js Bindings	TTSR regex engine wrapper

---

tests/ — Test Suite

File / Directory	System Label(s)	Description
tests/smoke/run.ts	Integration Tests	Test runner for smoke tests
tests/smoke/test-help.ts	Integration Tests	Smoke test for help command
tests/smoke/test-init.ts	Integration Tests	Smoke test for initialization
tests/smoke/test-version.ts	Integration Tests	Smoke test for version command
tests/fixtures/run.ts	Integration Tests	Fixture-based test harness with recording replay
tests/fixtures/provider.ts	Integration Tests	Fixture provider and replayer for LLM turns
tests/fixtures/record.ts	Integration Tests	Recording fixture capture
tests/fixtures/recordings/*.json	Integration Tests	Pre-recorded LLM agent interaction fixtures
tests/live/run.ts	Integration Tests	Live API roundtrip test runner
tests/live/test-anthropic-roundtrip.ts	Integration Tests, AI Providers	Live Anthropic API integration test
tests/live/test-openai-roundtrip.ts	Integration Tests, AI Providers	Live OpenAI API integration test
tests/live-regression/run.ts	Integration Tests	Live regression test runner
tests/repro-worktree-bug/*.mjs	Integration Tests, Worktree	Worktree bug reproduction scripts

---

scripts/ — Build & Utility

File	System Label(s)	Description
scripts/dev.js	Build System	Dev supervisor — tsc and resource watcher
scripts/dev-cli.js	Build System	CLI development mode runner
scripts/watch-resources.js	Build System	Resource file watcher for hot reload
scripts/bump-version.mjs	Build System	Version bumper for package.json and platform packages
scripts/sync-pkg-version.cjs	Build System	Sync pkg/package.json with workspace version
scripts/copy-resources.cjs	Build System	Resource file copier for distribution
scripts/copy-export-html.cjs	Build System	HTML export asset copier
scripts/copy-themes.cjs	Build System	Theme file copier
scripts/link-workspace-packages.cjs	Build System	Workspace package symlink manager
scripts/ensure-workspace-builds.cjs	Build System	Postinstall build checker
scripts/build-web-if-stale.cjs	Build System	Conditional web build trigger
scripts/stage-web-standalone.cjs	Build System	Web standalone staging
scripts/generate-changelog.mjs	Build System	Changelog generator from commits
scripts/update-changelog.mjs	Build System	Changelog updater
scripts/version-stamp.mjs	Build System	Version timestamp generator
scripts/validate-pack.sh	Build System	Package validation script
scripts/validate-pack.js	Build System	Package validation (Node.js)
scripts/install-pi-global.js	Build System	Global installation helper
scripts/uninstall-pi-global.js	Build System	Global uninstallation helper
scripts/install-hooks.sh	Build System, SF Workflow	Git hook installer
scripts/secret-scan.sh	Build System, Auth/OAuth	Secret scanning for credentials
scripts/docs-prompt-injection-scan.sh	Build System	Prompt injection detection in docs
scripts/check-skill-references.mjs	Build System, Skills	Skill reference validator
scripts/preview-dashboard.ts	Web Mode	Dashboard preview server
scripts/ci_monitor.cjs	Build System	CI monitoring dashboard
scripts/recover-sf-1364.sh	Build System, Migration	Recovery script for issue #1364
scripts/recover-sf-1364.ps1	Build System, Migration	Recovery script for issue #1364 (PowerShell)
scripts/recover-sf-1668.sh	Build System, Migration	Recovery script for issue #1668
scripts/recover-sf-1668.ps1	Build System, Migration	Recovery script for issue #1668 (PowerShell)

---

System → File Reverse Index

Quick lookup: which files are part of each system?

System	Key Files (abbreviated)
Agent Core	pi-agent-core/src/*, pi-coding-agent/src/core/agent-session.ts, agent-loop.ts, agent.ts, event-bus.ts, sdk.ts
AI Providers	pi-ai/src/providers/, pi-ai/src/stream.ts, pi-ai/src/models.ts
API Routes	web/app/api/**/*.ts
AST	native/crates/ast/*, packages/native/src/ast/
Async Jobs	src/resources/extensions/async-jobs/*
Auth / OAuth	pi-ai/src/utils/oauth/*, src/web/web-auth-storage.ts, core/auth-storage.ts, src/pi-migration.ts, aws-auth/index.ts, web/lib/auth.ts
Auto Engine	src/resources/extensions/sf/auto*.ts, sf/auto-loop.ts, sf/auto-supervisor.ts, sf/unit-runtime.ts
Bg Shell	src/resources/extensions/bg-shell/*
Browser Tools	src/resources/extensions/browser-tools/*
Build System	scripts/*, native/crates/engine/build.rs
CLI	src/cli.ts, src/cli-web-branch.ts, src/help-text.ts, src/update*.ts, pi-coding-agent/src/cli.ts, src/worktree-cli.ts
CMux	src/resources/extensions/cmux/index.ts
Commands	sf/commands*.ts, sf/exit-command.ts, sf/undo.ts, sf/kill.ts, pi-coding-agent/src/core/slash-commands.ts
Compaction	pi-coding-agent/src/core/compaction*.ts, core/compaction/*
Config	src/app-paths.ts, src/models-resolver.ts, src/remote-questions-config.ts, src/wizard.ts, core/defaults.ts, core/constants.ts, config.ts
Context7	src/resources/extensions/context7/index.ts
Doctor / Diagnostics	sf/doctor*.ts, sf/collision-diagnostics.ts, core/diagnostics.ts, web/lib/diagnostics-types.ts, web/app/api/doctor/, forensics/
Event System	pi-coding-agent/src/core/event-bus.ts, sf/auto-observability.ts
Extension Registry	src/extension-discovery.ts, src/extension-registry.ts, src/bundled-extension-paths.ts
Extensions	pi-coding-agent/src/core/extensions/*, src/resource-loader.ts
File Search	native/crates/engine/src/grep.rs, glob.rs, fd.rs, fs_cache.rs, packages/native/src/grep/, fd/, core/tools/grep.ts, find.ts
SF Workflow	src/resources/extensions/sf/* (non-auto), sf/reports.ts, sf/notifications.ts, sf/prompts/, sf/workflow-templates/
Google Search	src/resources/extensions/google-search/index.ts
Headless Mode	src/headless*.ts
Image Processing	native/crates/engine/src/image.rs, packages/native/src/image/, utils/image-.ts, web/lib/image-utils.ts
Integration Tests	tests/**/*
Loader / Bootstrap	src/loader.ts, src/resource-loader.ts, src/tool-bootstrap.ts, src/bundled-resource-path.ts, sf/bootstrap/*
LSP	pi-coding-agent/src/core/lsp/*
Mac Tools	src/resources/extensions/mac-tools/*
MCP Server/Client	src/mcp-server.ts, src/resources/extensions/mcp-client/index.ts, vscode-extension/src/sf-client.ts, modes/rpc/*
Memory Extension	pi-coding-agent/src/resources/extensions/memory/*
Migration	sf/migrate/, src/pi-migration.ts, pi-coding-agent/src/migrations.ts, scripts/recover-.sh
Modes	pi-coding-agent/src/modes/*
Model System	pi-coding-agent/src/core/model-.ts, pi-ai/src/models.ts, pi-ai/src/api-registry.ts, sf/model-router.ts
Native / Rust Tools	native/crates/engine/src/*
Node.js Bindings	packages/native/src/*
Onboarding	src/onboarding.ts, src/wizard.ts, web/components/sf/onboarding/, web/app/api/onboarding/
Permissions	core/extensions/project-trust.ts, core/auth-storage.ts
Remote Questions	src/resources/extensions/remote-questions/*
Search the Web	src/resources/extensions/search-the-web/*
Session Management	pi-coding-agent/src/core/session-manager.ts, core/settings-manager.ts, web/app/api/session/*
Skills	src/resources/skills/*, sf/skill-telemetry.ts, sf/preferences-skills.ts, core/skills.ts
Slash Commands	src/resources/extensions/slash-commands/*
State Machine	sf/state.ts, sf/history.ts, sf/json-persistence.ts, sf/memory-store.ts, sf/reactive-graph.ts, core/agent-session.ts, web/lib/sf-workspace-store.tsx
Studio App	studio/*
Subagent	src/resources/extensions/subagent/, src/resources/agents/
Syntax Highlighting	native/crates/engine/src/highlight.rs, packages/native/src/highlight/*
Text Processing	native/crates/engine/src/diff.rs, html.rs, text.rs, truncate.rs, json_parse.rs, stream_process.rs
Tool System	pi-coding-agent/src/core/tools/*, core/bash-executor.ts, core/exec.ts
TTSR	src/resources/extensions/ttsr/, native/crates/engine/src/ttsr.rs, packages/native/src/ttsr/
TUI Components	packages/pi-tui/src/, pi-coding-agent/src/modes/interactive/components/, pi-coding-agent/src/modes/interactive/controllers/*
Universal Config	src/resources/extensions/universal-config/*
Voice	src/resources/extensions/voice/*
VS Code Extension	vscode-extension/src/*
Web Mode	src/web/*.ts, src/web-mode.ts
Web UI	web/app/.tsx, web/components/, web/hooks/, web/lib/
Worktree	src/worktree-cli.ts, src/worktree-name-gen.ts, sf/worktree*.ts, tests/repro-worktree-bug/*