Skip to content

AGENTS.md

Latest commit

 

History

History
63 lines (39 loc) · 4.12 KB

AGENTS.md

File metadata and controls

63 lines (39 loc) · 4.12 KB

AGENTS.md

Task Completion Requirements

  • All of bun fmt, bun lint, and bun typecheck must pass before considering tasks completed.
  • NEVER run bun test. Always use bun run test (runs Vitest).

Project Snapshot

T3 Code is a minimal web GUI for using coding agents like Codex and Claude.

This repository is a VERY EARLY WIP. Proposing sweeping changes that improve long-term maintainability is encouraged.

Core Priorities

  1. Performance first.
  2. Reliability first.
  3. Keep behavior predictable under load and during failures (session restarts, reconnects, partial streams).

If a tradeoff is required, choose correctness and robustness over short-term convenience.

Maintainability

Long term maintainability is a core priority. If you add new functionality, first check if there is shared logic that can be extracted to a separate module. Duplicate logic across multiple files is a code smell and should be avoided. Don't be afraid to change existing code. Don't take shortcuts by just adding local logic to solve a problem.

Package Roles

  • apps/server: Node.js WebSocket server. Wraps Codex app-server (JSON-RPC over stdio), serves the React web app, and manages provider sessions.
  • apps/web: React/Vite UI. Owns session UX, conversation/event rendering, and client-side state. Connects to the server via WebSocket.
  • packages/contracts: Shared effect/Schema schemas and TypeScript contracts for provider events, WebSocket protocol, and model/session types. Keep this package schema-only — no runtime logic.
  • packages/shared: Shared runtime utilities consumed by both server and web. Uses explicit subpath exports (e.g. @t3tools/shared/git) — no barrel index.

Codex App Server (Important)

T3 Code is currently Codex-first. The server starts codex app-server (JSON-RPC over stdio) per provider session, then streams structured events to the browser through WebSocket push messages.

How we use it in this codebase:

  • Session startup/resume and turn lifecycle are brokered in apps/server/src/codexAppServerManager.ts.
  • Provider dispatch and thread event logging are coordinated in apps/server/src/providerManager.ts.
  • WebSocket server routes NativeApi methods in apps/server/src/wsServer.ts.
  • Web app consumes orchestration domain events via WebSocket push on channel orchestration.domainEvent (provider runtime activity is projected into orchestration events server-side).

Docs:

Reference Repos

Use these as implementation references when designing protocol handling, UX flows, and operational safeguards.

Fork-specific: Kiro Provider

This repo (t3code-kiro) is a fork of pingdotgg/t3code that patches a Kiro ACP provider on top of upstream. Before making changes that touch providers, the composer, or ACP:

  • Read PATCH.md for the maintenance guide (sync workflow, conflict zones, verification checklist).
  • Read docs/KIRO.md for Kiro ACP protocol notes (OIDC auth, in-session session/set_model/session/set_mode switching, _kiro.dev/* ext methods, agent discovery).
  • Adding a new provider requires updating four hardcoded ProviderKind arrays in apps/web/src/composerDraftStore.ts — see "Hidden Traps" in PATCH.md. Missing one produces a silent no-op (model selection reverts in UI with no error).
  • Kiro's model and agent switch in-session via session/set_model and session/set_mode RPCs — no respawn. Do not pass --model at spawn time (it locks Kiro's model and makes subsequent set_model RPCs silent no-ops). Passing --agent at spawn is safe.
  • Kiro's Plan sidebar wiring lives in apps/server/src/provider/acp/KiroAcpExtension.ts. Two sources feed turn.plan.updated via one emitter with per-turn dedup: native ACP kind: "plan" + todo_list tool-call state machine (create seeds, complete flips; 1-based string IDs match Kiro's completed_task_ids convention). See docs/KIRO.md → "Plan Sidebar Wiring" for state-model details.