Skip to content
Merged
Show file tree
Hide file tree
Changes from 10 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
105 changes: 27 additions & 78 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,103 +1,52 @@
# T3 Code

T3 Code is a minimal web GUI for coding agents made by [Pingdotgg](https://github.com/pingdotgg). This project is a downstream fork of [T3 Code](https://github.com/pingdotgg/t3code) customised to my utility and includes various PRs/feature additions from the upstream repo. Thanks to the team and its maintainers for keeping it OSS and an upstream to look up to.
T3 Code is a minimal web GUI for coding agents (currently Codex and Claude, more coming soon).
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Description: Search for provider implementations beyond Codex and Claude

# Search for provider kind definitions
echo "=== Checking ProviderKind enum/type definitions ==="
rg -n "ProviderKind" --type=ts -A 5 | head -30

# Search for provider configurations
echo -e "\n=== Checking provider configurations ==="
rg -n "anthropic|openai|gemini|cursor|copilot" --type=ts -i -g '!node_modules' -g '!*.test.ts' | head -20

Repository: aaditagrawal/t3code

Length of output: 4011


Update README to accurately list all supported providers.

The README claims support for "currently Codex and Claude, more coming soon," but the codebase contains evidence of additional provider support: the code includes CopilotModelOptions, CursorModelOptions, and GeminiCliModelOptions in packages/contracts/src/orchestration.ts, plus Copilot package bundling in the build script. Update the provider list to match what the fork actually supports rather than narrowing the scope to just Codex and Claude.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@README.md` at line 3, Update the README provider list to reflect actual
supported providers: replace the line claiming "currently Codex and Claude" with
a comprehensive list that includes Codex, Claude, Copilot (CopilotModelOptions),
Cursor (CursorModelOptions), and Gemini CLI (GeminiCliModelOptions) and any
other providers referenced in the codebase; ensure the phrasing matches the
project scope (e.g., "Supports Codex, Claude, Copilot, Cursor, Gemini CLI, and
more") and mention bundling where relevant (referencing the Copilot package
bundling in build scripts) so the README accurately mirrors the symbols and
features present in packages/contracts/src/orchestration.ts and the build
configuration.


It supports Codex, Claude Code, Cursor, Copilot, Gemini CLI, Amp, Kilo, and OpenCode.
## Installation

(NOTE: Amp /mode free is not supported, as Amp Code doesn't support it in headless mode - since they need to show ads for that business model to work.)

## Why the fork?

This fork is designed to keep up a faster rate of development customised to my needs (and if you want, _yours_ as well -> Submit an issue and I'll make a PR for it). There's certain features which will (rightly) remain out of scope/priority for the project at its scale, but might be required for someone like me.

### Multi-provider support

Adds full provider adapters (server managers, service layers, runtime layers) for agents that are not yet on the upstream roadmap:

| Provider | What's included |
| ----------- | ------------------------------------------------------------------------- |
| Amp | Adapter + `ampServerManager` for headless Amp sessions |
| Copilot | Adapter + CLI binary resolution + text generation layer |
| Cursor | Adapter + ACP probe integration + usage tracking |
| Gemini CLI | Adapter + `geminiCliServerManager` with full test coverage |
| Kilo | Adapter + `kiloServerManager` + OpenCode-style server URL config |
| OpenCode | Adapter + `opencodeServerManager` with hostname/port/workspace config |
| Claude Code | Full adapter with permission mode, thinking token limits, and SDK typings |

### UX enhancements

| Feature | Description |
| ------------------- | ------------------------------------------------------------------------------------------ |
| Settings page | Dedicated route (`/settings`) for theme, accent color, and custom model slug configuration |
| Accent color system | Preset palette with contrast-safe terminal color injection across the entire UI |
| Theme support | Light / dark / system modes with transition suppression |
| Command palette | `Cmd+K` / `Ctrl+K` palette for quick actions, script running, and thread navigation |
| Sidebar search | Normalized thread title search with instant filtering |
| Plan sidebar | Dedicated panel for reviewing, downloading, or saving proposed agent plans |
| Terminal drawer | Theme-aware integrated terminal with accent color styling |

### Branding & build

- Custom abstract-mark app icon with macOS icon composer support
- Centralized branding constants for easy identity swaps
- Desktop icon asset generation pipeline from SVG source
> [!WARNING]
> T3 Code currently supports Codex and Claude.
> Install and authenticate at least one provider before use:
>
> - Codex: install [Codex CLI](https://github.com/openai/codex) and run `codex login`
> - Claude: install Claude Code and run `claude auth login`
Comment on lines +11 to +12
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

🌐 Web query:

OpenAI Codex CLI GitHub repository installation

💡 Result:

The OpenAI Codex CLI GitHub repository is https://github.com/openai/codex. Installation methods: 1. Via npm (recommended): npm install -g @openai/codex 2. Via Homebrew (macOS): brew install --cask codex (or brew install codex in some sources) 3. Download prebuilt binary from latest release: https://github.com/openai/codex/releases. Choose based on platform, e.g.: - macOS Apple Silicon: codex-aarch64-apple-darwin.tar.gz - macOS x86_64: codex-x86_64-apple-darwin.tar.gz - Linux x86_64: codex-x86_64-unknown-linux-musl.tar.gz - Extract and add to PATH. After installation, run 'codex' to start. First run prompts sign-in with ChatGPT account (recommended for Plus/Pro/etc. plans) or API key. Note: There is a legacy TypeScript version in codex/codex-cli subdir, but current is Rust-based main CLI. To build from source (advanced): Clone repo, follow docs/Installing & building (not detailed in results, but repo has instructions).

Citations:


🌐 Web query:

Claude Code CLI authentication command

💡 Result:

The authentication command for Claude Code CLI is claude auth login. This signs you into your Anthropic account (Claude Pro/Max/Team/Enterprise). Options include --email to pre-fill email, --sso for SSO, and --console for Anthropic Console API billing. Related commands: - claude auth logout: Log out. - claude auth status: Check status (--text for readable output). On first claude run, it auto-prompts browser login if needed. Credentials are stored securely (macOS Keychain, else ~/.claude/.credentials.json). For API keys, use env vars like ANTHROPIC_API_KEY instead of login.

Citations:


Fix Codex CLI authentication instruction.

The Codex CLI URL is correct, but the authentication flow is inaccurate. The codex login command doesn't exist; Codex auto-prompts for sign-in on the first run of codex. Update line 11 to:

> - Codex: install [Codex CLI](https://github.com/openai/codex) and run `codex`

The Claude instruction on line 12 is correct as-is.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@README.md` around lines 11 - 12, Update the Codex CLI authentication
instruction in the README: replace the incorrect `codex login` command with the
correct first-run invocation `codex` in the bullet that reads "- Codex: install
[Codex CLI](https://github.com/openai/codex) and run `codex login`", leaving the
Claude line unchanged.


### Developer tooling
### Run without installing

- `sync-upstream-pr-tracks` script for tracking cherry-picked upstream PRs
- `cursor-acp-probe` for testing Cursor Agent Communication Protocol
- Custom alpha workflow playbook (`docs/custom-alpha-workflow.md`)
- Upstream PR tracking config (`config/upstream-pr-tracks.json`)
```bash
npx t3
```

## Getting started
### Desktop app

### Quick install (recommended)
Install the latest version of the desktop app from [GitHub Releases](https://github.com/pingdotgg/t3code/releases), or from your favorite package registry:
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Description: Check for releases in both upstream and fork repositories

echo "=== Fork releases (aaditagrawal/t3code) ==="
gh api repos/aaditagrawal/t3code/releases --jq '.[0:3] | .[] | {tag_name, published_at, name}'

echo -e "\n=== Upstream releases (pingdotgg/t3code) ==="
gh api repos/pingdotgg/t3code/releases --jq '.[0:3] | .[] | {tag_name, published_at, name}'

Repository: aaditagrawal/t3code

Length of output: 456


🏁 Script executed:

#!/bin/bash
# Check for git tags (releases) in the repository
echo "=== Git tags in the fork ==="
git tag -l | head -20

echo -e "\n=== Recent commits mentioning release ==="
git log --oneline --grep="release" | head -10

echo -e "\n=== Check for release-related files ==="
git ls-files | grep -iE "(release|changelog|news|version)" | head -20

echo -e "\n=== Git remote URL ==="
git config --get remote.origin.url

Repository: aaditagrawal/t3code

Length of output: 435


🏁 Script executed:

#!/bin/bash
echo "=== docs/release.md content ==="
cat docs/release.md

echo -e "\n=== .github/workflows/release.yml (first 50 lines) ==="
head -50 .github/workflows/release.yml

echo -e "\n=== apps/marketing/src/lib/releases.ts (first 30 lines) ==="
head -30 apps/marketing/src/lib/releases.ts

Repository: aaditagrawal/t3code

Length of output: 8223


🏁 Script executed:

#!/bin/bash
echo "=== README.md lines 20-40 (full context) ==="
sed -n '20,40p' README.md

echo -e "\n=== All upstream references in README ==="
grep -n "pingdotgg\|github.com.*t3code" README.md

Repository: aaditagrawal/t3code

Length of output: 670


Update GitHub Releases URL to reference the fork, not upstream.

Line 22 directs users to https://github.com/pingdotgg/t3code/releases, but the fork at aaditagrawal/t3code maintains independent release infrastructure (see docs/release.md and .github/workflows/release.yml). Update the link to https://github.com/aaditagrawal/t3code/releases to direct users to the fork's releases. Also update apps/marketing/src/lib/releases.ts which hardcodes pingdotgg/t3code in the RELEASES_URL and API_URL constants.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@README.md` at line 22, Update the GitHub Releases link in README.md to point
to the fork's releases (change https://github.com/pingdotgg/t3code/releases to
https://github.com/aaditagrawal/t3code/releases) and update the hardcoded
constants in apps/marketing/src/lib/releases.ts (RELEASES_URL and API_URL) to
reference "aaditagrawal/t3code" instead of "pingdotgg/t3code"; modify the string
values for RELEASES_URL and API_URL in that module so the marketing app and
README both direct to the fork's releases endpoint.


Run the interactive installer — it detects your OS, checks prerequisites (git, Node.js ≥ 24, bun ≥ 1.3.9), installs missing tools, and lets you choose between development/production and desktop/web builds:
#### Windows (`winget`)

```bash
# macOS / Linux / WSL
bash <(curl -fsSL https://raw.githubusercontent.com/aaditagrawal/t3code/main/scripts/install.sh)
winget install T3Tools.T3Code
```

```powershell
# Windows (Git Bash, MSYS2, or WSL)
bash <(curl -fsSL https://raw.githubusercontent.com/aaditagrawal/t3code/main/scripts/install.sh)
```
#### macOS (Homebrew)

The installer supports **npm, yarn, pnpm, bun, and deno** detection, and will auto-install bun if no suitable package manager is found. It provides OS-specific install instructions for any missing prerequisites (Homebrew on macOS, apt/dnf/pacman on Linux, winget on Windows).

### Manual build
```bash
brew install --cask t3-code
```

> [!WARNING]
> You need at least one supported coding agent installed and authorized. See the supported agents list below.
#### Arch Linux (AUR)

```bash
# Prerequisites: Bun >=1.3.9, Node >=24.13.1
git clone https://github.com/aaditagrawal/t3code.git
cd t3code
bun install
bun run dev
yay -S t3code-bin
```

## Supported agents
## Some notes

We are very very early in this project. Expect bugs.

- [Codex CLI](https://github.com/openai/codex) (requires v0.37.0 or later)
- [Claude Code](https://github.com/anthropics/claude-code) — **not yet working in the desktop app**
- [Cursor](https://cursor.sh)
- [Copilot](https://github.com/features/copilot)
- [Gemini CLI](https://github.com/google-gemini/gemini-cli)
- [Amp](https://ampcode.com)
- [Kilo](https://kilo.dev)
- [OpenCode](https://opencode.ai)
We are not accepting contributions yet.

## Contributing
## If you REALLY want to contribute still.... read this first

Read [CONTRIBUTING.md](./CONTRIBUTING.md) before opening an issue or PR.

Need support? Join the [Discord](https://discord.gg/jn4EGJjrvv).

## Notes

- This project is very early in development. Expect bugs. (Especially with my fork)
- Maintaining a custom fork or alpha branch? See [docs/custom-alpha-workflow.md](docs/custom-alpha-workflow.md).
Loading
Loading