Development

Build and run TrueDeck from source. Product docs: Getting started.

Prerequisites

• Node.js 20+
• npm (lockfile is npm)
• Git
• Rust + MSVC Build Tools (Windows) for truedeck-backend
• Agent CLIs you want to test (claude, codex, cursor-agent, …)

Clone and install

git clone https://github.com/WutIsHummus/TrueDeck.git
cd TrueDeck
npm install

postinstall runs electron-builder install-app-deps so node-pty matches Electron’s ABI.

Scripts (package.json)

Script	What it does
npm start / npm run studio / npm run dev	Electron Studio via electron-vite dev
npm run tui / npm run dev:tui	Blessed TUI (tsx tui/index.ts)
npm run build	Production compile → out/
npm run preview	electron-vite preview
npm run icons	Regenerate PNG/ICO from resources/icon.svg

| npm run build:backend | Build truedeck-backend → resources/bin/ | | npm run dist | icons + backend + build + electron-builder --dir | | npm run dist:win | Windows NSIS + portable installer | | npx truedeck | CLI entry (bin/truedeck.js) when linked |

electron-vite layout

Source	Output role
electron/main/	Main process
electron/preload/	Preload bridge
src/	Renderer (React)
electron.vite.config.ts	Build config

TypeScript projects: tsconfig.json, tsconfig.node.json, tsconfig.web.json.

Rust backend

Full backend

npm run build:backend
npm start
# log: [backend] rust truedeck-backend …

Details: RUST-BACKEND.md.

PTY-only sidecar

npm run build:backend
# log: [backend] primary engine: rust truedeck-backend

Details: FAST-PTY.md.

Without binaries, TypeScript + node-pty is the fallback.

Packaging

Windows example:

npm run dist:win

Outputs under release/ (see package.json build.directories.output). Extra resources include:

• resources/bin (native backends)
• resources/mcp-server
• resources/agent-frame
• icons

appId: dev.truedeck.app.

Repo layout for contributors

src/ # Studio UI
electron/main/ # Main process services
electron/preload/ # IPC surface
electron/shared/types.ts
resources/agent-frame/ # truedeck-frame.mjs
resources/mcp-server/ # truedeck-mcp.mjs
crates/truedeck-backend/

tui/ # Non-Electron deck
tools/ # icon generator, rust build helpers, MemPalace scripts
docs/ # Documentation site (this folder)

Coding notes

• Prefer editing documentation under docs/ and root README.md for user-facing changes
• Agent memory protocol for work in other repos is separate (TrueDeck injects into those projects)
• Do not commit secrets; agent CLI auth stays with each vendor CLI
• Windows ConPTY quirks: test real agent TUIs after PTY changes

Contributing

There is no separate CONTRIBUTING.md in-repo yet. Practical guide:

1. Fork / branch from the default branch
2. Keep changes focused; match existing TypeScript style
3. Document user-visible behavior under docs/
4. Verify npm start still launches; if you touch PTY, test spawn + resize + exit
5. Open a PR with a short summary of behavior and any new env/settings keys

License: MIT (LICENSE).

Related

• Architecture
• Troubleshooting
• Configuration