t1code

When exposing the T3 Code server to a network (outside of localhost), follow these security practices:

1. Set an Auth Token: Always use --auth-token (or T3CODE_AUTH_TOKEN). Treat this token like a password.
2. Use Bootstrap File Descriptors: If you control the process launcher, prefer using --bootstrap-fd <fd>. This allows the launcher to send a one-shot JSON envelope containing the auth token over an inherited file descriptor, preventing the token from appearing in process environment variables or command-line arguments.
3. Restrict Binding: Instead of binding to all interfaces (0.0.0.0), prefer binding to a specific trusted interface, such as a LAN IP or a Tailscale Tailnet IP.

The when property allows you to restrict a shortcut to specific application states using boolean expressions.

Context Keys:

• terminalFocus
• terminalOpen

Operators:

• ! (not)
• && (and)
• || (or)
• ( ) (parentheses for grouping)

Examples:

• "when": "terminalFocus"
• "when": "terminalOpen && !terminalFocus"
• "when": "terminalFocus || terminalOpen"

Note: Unknown condition keys evaluate to false.

{
  "key": "mod+n",
  "command": "chat.new",
  "when": "!terminalFocus"
}

When multiple rules match a key event, T3 Code determines which one to execute based on these rules:

1. Array Order: Rules are evaluated in the order they appear in the JSON array.
2. Last Match Wins: For a specific key event, the last rule in the array where both the key matches and the when condition evaluates to true is the one that executes.
3. Cross-Command Precedence: Precedence is applied across all commands, not just within the same command type. This allows you to override a default command with a different one by placing a new rule later in the array.

Each rule in the keybindings.json array follows this shape:

• key (required): A string representing the shortcut (e.g., mod+j, ctrl+k).
• command (required): The action ID to execute.
• when (optional): A boolean expression string that controls when the shortcut is active based on the current context.

Invalid rules are silently ignored by the application.

{
  "key": "mod+shift+g",
  "command": "terminal.new",
  "when": "terminalFocus"
}

If you want to contribute to or develop t1code, follow these steps to clone the repository, install dependencies, and run the TUI in development mode:

1. Clone the repository.
2. Navigate into the directory.
3. Install dependencies using bun install.
4. Start the development TUI using bun dev:tui.

git clone https://github.com/maria-rcks/t1code.git
cd t1code
bun install
bun dev:tui

You can run the t1code terminal UI immediately without a permanent installation using bunx.

bunx @maria_rcks/t1code

To install the t1code CLI globally on your system using Bun, use the following command:

bun add -g @maria_rcks/t1code

T3 Code reads custom keybindings from a JSON file located at ~/.t3/keybindings.json. The file must contain a JSON array of rule objects. If the file is invalid or contains invalid rules, they will be ignored and warnings will be logged by the server.

[
  { "key": "mod+g", "command": "terminal.toggle" },
  { "key": "mod+shift+g", "command": "terminal.new", "when": "terminalFocus" }
]

To access T3 Code from another device (phone, tablet, etc.), you must use the built web app rather than the local Vite redirect mode.

Follow these steps:

1. Build the project.
2. Generate a secure token.
3. Start the server bound to 0.0.0.0 to listen on all IPv4 interfaces.

Note: Ensure your OS firewall allows inbound TCP traffic on the port you select (e.g., 3773).

bun run build
TOKEN="$(openssl rand -hex 24)"
bun run --cwd apps/server start -- --host 0.0.0.0 --port 3773 --auth-token "$TOKEN" --no-browser

If you use Tailscale, you can bind the server directly to your Tailnet address for improved security. This limits exposure compared to binding to 0.0.0.0.

Use the following command to automatically detect your Tailscale IPv4 address and start the server:

TAILNET_IP="$(tailscale ip -4)"
TOKEN="$(openssl rand -hex 24)"
bun run --cwd apps/server start -- --host "$(tailscale ip -4)" --port 3773 --auth-token "$TOKEN" --no-browser

The effect-codex-app-server package uses a specific set of error classes to represent failures in the server lifecycle, transport, or protocol. You can use the CodexAppServerError union type to catch and handle these errors.

Common error types include:

• CodexAppServerSpawnError: Occurs when the server process fails to start.
• CodexAppServerProcessExitedError: Occurs when the server process terminates unexpectedly.
• CodexAppServerProtocolParseError: Occurs when a protocol message cannot be parsed.
• CodexAppServerTransportError: Occurs during communication transport failures.
• CodexAppServerRequestError: Represents application-level request errors (e.g., method not found, invalid params).

When the Electron app is ready, it executes a bootstrap() sequence to initialize the backend services and the main window. The bootstrap process performs the following steps:

1. Port Reservation: Uses NetService to reserve a loopback port for the backend.
2. Authentication: Generates a random 24-byte hex backendAuthToken.
3. WebSocket Setup: Constructs a backendWsUrl using the reserved port and the auth token (e.g., ws://127.0.0.1:PORT/?token=TOKEN).
4. IPC Registration: Registers all required IPC handlers.
5. Backend Start: Initiates the backend service.
6. Window Creation: Creates the mainWindow using createWindow().