threadlane: Instructions file for Codex

AGENTS.md

Guidance for coding agents working in the Threadlane repository.

Scope

This file applies to the entire repository.

Threadlane is a Rust workspace centered on a native GPUI desktop application (crates/threadlane-gpui). Keep changes focused, preserve the existing visual language, and prefer established project patterns over introducing new frameworks or dependencies.

Repository Map

• crates/threadlane-gpui/ — GPUI desktop application binary shell (main.rs + empty lib): window setup, logging, --dump-config, and composition of the threadlane-ui-* crates. Holds no product code; add new UI to a focused leaf crate instead.
• crates/threadlane-ui-workspace/ — window root (WorkspaceView): composes chat, sidebar, panels, terminal, settings, and GitHub over one AppState; owns global keybindings and background event pumps. Terminal tabs/menus, toolbar, unavailable state, and the bottom split use threadlane-ui-kit; this host retains project groups, PTYs, selection handoff and shell-identity close guards.
• crates/threadlane-ui-kit/ — controlled agent UI components shared by desktop and iOS: conversation, composer, reasoning/tool disclosures, decisions, session navigation, and result surfaces. Replaces threadlane-ui-session; extend this kit before adding another presentation path. examples/preview runs the shared saved-session workspace and a Components gallery on native GPUI and WASM (trunk serve from that folder). --import-session <jsonl> reads canonical durable history into ignored session.local.json; previews never modify the original session. Agents profile/status/header/activity presentation (including the shared chat tool disclosures), sidebar/workspace/composer atoms, environment and Git menu presentation, token-efficiency rows, context-meter primitives, and tool output renderers belong in the kit; host services and file guards remain in feature crates. Composer @ file picker presentation, caret-query parsing, matching, insertion formatting, and scoped bindings live in threadlane-ui-kit::file_completion; the desktop host retains asynchronous inventory/existence services and must recheck composer identity, checkout, picker generation, and dismissal after a probe yields. Preview imports capture a read-only Git file inventory and never probe the browser host filesystem. Responsive workspace geometry, compact right-panel focus, sidebar controls and split restoration live in the kit and are reused by desktop and native/WASM preview. Agent worktree controls and Discard confirmation also live in the kit; native hosts retain guarded daemon/Git operations, and preview imports capture read-only branch diffs and availability. Shared font registration lives in the theme crate. Serializable token-efficiency report types live in threadlane-protocol::efficiency; the read-only journal projector stays in the runtime harness.
• crates/threadlane-ui-theme/ — shared GPUI visual language: theme registry wiring, design tokens (WINDOW_CONTROLS_CLEARANCE, overlay_scrim()), bundled themes/threadlane.json, and vendored assets/icons/. Depends only on GPUI/kit plus threadlane-project for the global dir; every screen crate uses it, never the reverse.
• crates/threadlane-daemon/ — headless, GPUI-free service core a future daemon process wraps: session discovery/projection, chat turn services (chat: prompt execution, titles, ACP config), the agent-event adapter, background services (provider_auth, settings, updater), worktree setup, the automation application service, the next_event_batch stream helper, and the picker-facing model catalog (catalog: provider inventory, live discovery caches, effort metadata — the four *_and_update refresh wrappers that need Entity<AppState> live in threadlane-ui-settings, which the workspace shell imports directly), and the read-only conversation-text scan (conversation_search). threadlane-ui-state re-exports all of it for compatibility.
• crates/threadlane-ui-sidebar/ — project/session sidebar plus the shared keybindable BeginNewTask action (owned here because the sidebar's buttons dispatch it; the workspace shell imports the type for its cmd-N binding). Its Snoozed group is presentation-only and local-only: snooze records live in .threadlane/session_snooze.json per workdir (written through threadlane_ui_state::SessionSnoozeWriter) and only reorder history rows — they never schedule, stop, or delay an agent, touch a worktree, acknowledge a result, or reach the daemon. Reconciliation (AppState::reconcile_session_snoozes plus the sidebar's single deadline task) decides visibility; expired/invalid records fail open. Complete session cards, action menus, snoozed/empty history presentation, and archive/remove dialog surfaces live in threadlane-ui-kit; this host retains history filtering/cache/virtualization, canonical snooze mapping, and guarded service callbacks. Archive icons preserve the existing direct archive for ordinary checkouts and confirmation for worktrees; menu archive/remove always use confirmation.
• crates/threadlane-ui-state/ — durable desktop UI state, GPUI-free: AppState, app intent (actions/controller), and UI-only types (workspace page, composer/insert requests, GitHub tab). Session services moved to threadlane-daemon and are re-exported here (chat, discovery, projection, automation, provider_auth, settings, updater, worktree_setup, agent_events, catalog, session/projection types) so existing threadlane_ui_state::* paths keep working; file watching lives in threadlane-project::watcher.
• crates/threadlane-ui-terminal/ — self-contained PTY terminal view (TerminalView::new(PathBuf, cx)): portable-pty session, frame-budgeted parsing, and GPUI rendering. Depends on threadlane-ui-kit for shared terminal chrome, ANSI grid presentation, measured geometry, selection helpers, find/link presentation and keybindings, output menus/status/live-output controls, with no AppState or service-crate dependency; the workspace screen constructs it directly. Search workers, frame/URL validation and PTY lifecycle stay here.
• crates/threadlane-ui-chat/ — chat surface (ChatListView, CentralTab, composer/transcript/trajectory/context-meter): depends on threadlane-ui-state, threadlane-daemon (model catalog), threadlane-ui-theme, plus threadlane-ui-editor and threadlane-ui-mirror which it embeds.
• crates/threadlane-ui-editor/ — file editor view (EditorView, SaveFile action); depends only on threadlane-ui-state (+rfd, tracing).
• crates/threadlane-ui-mirror/ — computer-use live mirror (MirrorView over threadlane-protocol::live frames); depends only on threadlane-ui-state. NOTE: never use use super::* in #[cfg(test)] modules of GPUI-heavy crates — the glob pulls gpui macros into test scope and cargo check --tests hangs in macro expansion (needs recursion_limit >= 2048, and even that hangs). Explicit test imports compile in ~2s at the default limit. Hit in ui-mirror and ui-workspace.
• crates/threadlane-ui-settings/ — settings screen plus the model-catalog *_and_update refresh wrappers (they need Entity<AppState>, so they cannot live in GPUI-free threadlane-daemon).
• crates/threadlane-ui-github/ — GitHub issues/PRs/diffs/review timelines; view::init registers its actions.
• crates/threadlane-ui-right-panel/ — git review, draft PRs, embedded browser (macOS gpui-wry view, stub elsewhere), and file surfaces. retain_review_selection is specified by tests.rs; keep them in sync.
• crates/threadlane-runtime/ — agent execution engine, harness V2 durability, provider routing, compaction, and turn driver. Depends on threadlane-provider, never the reverse.
• crates/threadlane-coding-agent/ — coding-agent engine: CodingAgent runtime, durable harness, subagents, scheduler, mailbox, capabilities, controller (SessionController; also home of the SessionRuntime alias, runtime_status_text, spawn_session_runtime_construction, and the test-support provider-injection helper consumed by the GPUI crates), config_dump, the acp_stub_agent test fixture plus engine integration tests/, and the session-owned adapters it is built from (commands, computer, credentials, mcp). The threadlane-gpui binary calls config_dump and owns process_environment directly. There is no separate threadlane-session crate; UI crates import threadlane_coding_agent::controller directly.
• crates/threadlane-acp-engine/ — external-agent turn engine (AcpEngine::run_turn, generate_title), the AgentEvent bridge, the workspace-scoped session_workspace_client (single shared threadlane-tools path guard), and the ACP agent presets registry. Deps: threadlane-acp, -runtime, -permission, -tools, -project only; the coding-agent crate consumes it, never the reverse.
• crates/threadlane-provider/ — dependency-free provider layer: payload translation (convert), model registry, shared Tokio reactor (exec), and per-backend clients. Takes credentials as arguments/traits, never reads a credential store.
• crates/threadlane-protocol/ — shared contract types: wire shapes plus the model-visible message cluster (messages: AgentMessage, AgentToolDefinition, ReasoningEffort, …), user-interaction contracts (interaction: PermissionRequest/PermissionScope, QuestionRequest/QuestionAnswer, …), and the GPUI-free transcript helpers (transcript: row building, literal find_conversation_messages/matching_excerpt/next_find_match, prompt landmarks) shared by the UI transcript and the daemon conversation scan.
• crates/threadlane-tools/ — tool implementations and capability support.
• crates/threadlane-auth/ — authentication helpers.
• crates/threadlane-computer/ — native computer-use tools (macOS window listing, screenshots, input) behind the ComputerApproval trait; the coding-agent engine implements approval with its permission manager.
• crates/threadlane-git/ — git repository integration and PR review feedback (forge types, actionable-feedback extraction, tracking store, auto-address prompts). Agent-owned PR lifecycle instructions are shared from threadlane-prompt::git_workflow; native Git sessions expose credential-aware github_pr operations through github::agent. Keep read-only versus mutating tool-policy classification synchronized when adding actions; never turn local-only tasks or reply drafts into publication/merge authorization.
• crates/threadlane-updater/ — signed update checks, downloads, installation, and relaunch.
• crates/threadlane-wasi/ — WASI extension runner.
• extensions/ — WASI extensions built for wasm32-wasip1.
• scripts/build_extensions.sh — builds and deploys bundled extensions, agents, and prompts into .threadlane/.
• packaging/, .github/workflows/, and package metadata — release and platform packaging.