Skip to content

AGENTS.md

Latest commit

 

History

History
99 lines (64 loc) · 4.53 KB

AGENTS.md

File metadata and controls

99 lines (64 loc) · 4.53 KB
Raw

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:

Bundled Gas City Config

Bundled Gas City config lives under packages/gascity-config/config.

Key files:

  • city.toml: live city entrypoint used by bundled T3Code development runs.
  • pack.toml: root pack with bundled provider defaults and top-level patches.
  • packs/gastown/pack.toml: Gastown roles, formulas, named sessions, includes.
  • packs/maintenance/pack.toml: shared infrastructure included by Gastown.
  • .gc/site.toml: machine-local rig path bindings, not packaged city behavior.

Important semantics:

  • [[patches.agent]].dir is config scoping for city vs rig patches.
  • work_dir is runtime working-directory configuration for an agent.
  • Do not confuse dir with cwd/workdir.

GC Session Env Boundary

T3Code surfaces Gas City session metadata in the sidebar, including GC_* values. That does not guarantee every tool shell inherits the same env.

Rules:

  • Sidebar GC context describes the provider session.
  • Tool shells may run in separate child-process environments.
  • Empty GC_* in a shell does not prove GC session identity is missing.
  • When running gc/bd commands from tools, pass GC_ALIAS, GC_SESSION_ID, GC_SESSION_NAME, and GC_SESSION_ORIGIN explicitly if the command depends on them.

When debugging:

  • Use sidebar/session metadata as identity truth.
  • Use server/runtime code to verify env forwarding boundaries.
  • Do not assume gc prime exports shell variables; it emits agent prompt content.

T3Code DB Access

Follow docs/t3code-db-playbook.md before inspecting or repairing T3Code runtime databases. Do not use stock sqlite3 on T3Code state files. The app opens its main state through the Doltlite-backed persistence client, and thread metadata repairs must go through app-owned orchestration/projection paths.

Reference Repos

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