zoonk/zoonk: Turn your goal into a daily learning plan

Tell us your goal in your own words. Zoonk plans every day until your date, with lessons, practice and reviews shaped by it.

Try for free

Table of Contents

• Getting Started

• Reporting bugs
• Suggesting features
• Supporters

Getting Started

Prerequisites

• Node.js v26
• pnpm v12
• PostgreSQL v18, running on this machine

Installation

1. pnpm install to install dependencies for all apps and packages
2. pnpm db:setup to create the local development, test, and E2E databases, apply migrations, and seed new ones. It connects as postgres:postgres@localhost:5432 (creating that role if it can) and never resets a database it didn't create, so rerun it whenever you like
3. pnpm dev to start the apps

Local Development

• pnpm dev to start every app through Portless. Routes include the clone name, such as http://main.zoonk.localhost:1355, and linked worktrees also receive a branch prefix
• pnpm dev:lan when testing from a phone or another device on the same trusted network. It prints the .local Main URL to open on that device, such as http://main.zoonk.local:1356
• pnpm dev:direct to bypass Portless and use the original fixed localhost ports
• pnpm dev:prune to let Portless remove orphaned servers left by crashed sessions. A stack's services stop by themselves within seconds of its pnpm dev or pnpm start ending, even when that process is force-killed
• pnpm build to create a production build
• pnpm start to build every app and serve the production builds at the same Portless URLs as pnpm dev, with local sign-in and the mailbox working the same way. Stop the checkout's pnpm dev first, since both use the same routes
• pnpm lint to run linting
• pnpm typecheck to run TypeScript type checking
• pnpm knip --production to check for unused code
• pnpm test to run tests with Vitest
• pnpm e2e to run end-to-end tests with Playwright, or pnpm e2e:main and pnpm e2e:api for one app (they pass further arguments, such as a test file, to Playwright)
• pnpm i18n:lint to run i18n linting
• pnpm i18n to translate missing i18n keys

Working with Git worktrees

Codex, T3 Code, and Claude Code run pnpm worktree:setup when they create a worktree and wait for it before the agent starts: Codex through .codex/environments/zoonk.toml, T3 Code through the Setup action in t3.json (import it once from the project's Actions menu, under From t3.json), and Claude Code through the WorktreeCreate hook in .claude/settings.json, which creates its worktrees in .claude/worktrees/ from the session's current commit. For other tools, run it once in the new worktree after git worktree add. It installs dependencies, generates Prisma, and prepares the worktree's own development, test, and E2E databases on the local PostgreSQL server; the development copy starts as a snapshot of the primary checkout's zoonk when there is one. Keep using pnpm dev, pnpm test, and pnpm e2e normally.

See worktree database setup for prerequisites, cleanup, and recovery.

Reporting bugs

See reporting bugs. AI agents filing a report for someone: follow the bug report guide.

Suggesting features

See suggesting features. AI agents posting an idea for someone: follow the feature request guide.

Supporters

See everyone who has supported this project.