A System for Keeping Promises to Yourself.
Turn Intent Into Discipline.
About · Quick Start · Contributing · Core Features · Architecture · Documentation
Most productivity tools suffer from passive accumulation—tasks, habits, and aspirational goals are recorded with enthusiasm, then quietly neglected when friction strikes.
Intent is easy. Execution is difficult.
PACT is an open-source Personal Operating System (OS) built with Next.js 16, React 19, TypeScript 5, Tailwind CSS v4, and Supabase PostgreSQL to bridge the critical divide between intention and action. Rather than functioning as a passive checklist, PACT provides an active governance system unifying time-blocked planning, strategic milestone tracking, deep work focus sessions, integer-cents financial cash flow, and unbreakable accountability contracts.
- Unbreakable Accountability: Commitments are bound to explicit deadlines, confidential consequences, and strict resolution workflows.
- Temporal Truth: Time-blocked planning with bi-directional Google Calendar synchronization guarantees realistic daily execution capacity.
- Objective Proof Verification: Automated external connectors validate technical proof-of-work via GitHub, LeetCode, and Codeforces.
- Holistic Governance: Single unified operational system for tasks, strategic goals, scoped projects, recurring routines, deep work focus, and financial cash flow.
- Open Source & Beginner Friendly: Designed as a welcoming hub for first-time open-source contributors with single-file micro-issues, zero-database local setup, and fast-track PR reviews.
- Node.js:
v20.x(LTS recommended) - Package Manager:
npm(v10+) - Git: Installed and configured
# 1. Clone your fork or the repository
git clone https://github.com/TheVicky1/Pact_OS.git
cd Pact_OS
# 2. Install reproducible dependencies
npm ci
# 3. Configure local environment variables
cp .env.example .env.local
# 4. Start local development server
npm run devOpen http://localhost:3000 in your browser to access PACT.
Run the local verification suite prior to committing changes:
# Run ESLint check
npm run lint
# Run TypeScript type check
npm run typecheck
# Run automated domain, release, and security test matrix
npm test
# Run preflight release readiness audit
npm run release:check
# Run pre-commit secret scanner
node scratch/secret-scan.mjs
# Run documentation link verification
node scratch/check-links.mjs
# Run production build compilation
npm run buildPACT OS includes a multi-stage production Dockerfile and docker-compose.yml for self-hosted or staging environments:
# Build and start containerized PACT OS
docker compose up -d --build
# Verify operational readiness probe
curl -I http://localhost:3000/api/health💡 Having setup issues? Consult our Troubleshooting Guide or Production Deployment Runbook for detailed environment configuration.
Contributions are warmly welcomed! PACT is designed to be one of the most welcoming and beginner-friendly open-source destinations on GitHub.
🚀 New to Open Source? Start with a Micro-Contribution! We deliberately scope our beginner tasks into tiny, single-file micro-contributions (5–30 minutes of work) with exact file pointers, concrete acceptance criteria, and step-by-step guidance. 👉 Browse Live Good First Issues (28 Available) | 📖 Read the Beginner's Guide
- ⚡ Zero-Database Friction: Run the full application and all 44 automated test suites locally right away using
.env.example—no cloud database setup required. - 🎯 Highly Scoped Micro-Issues: Tasks touch one file (max two) with zero complex business logic, no database migrations, and clear verification steps.
- 🚀 Fast Maintainer Reviews: First-time contributor pull requests receive priority review from core maintainers (target turnaround under 48 hours).
- 🏛️ Permanent Recognition: Every merged contribution is permanently acknowledged in CONTRIBUTORS.md and on the GitHub Contributors Graph.
- Pick an Issue: Browse open Good First Issues.
- Claim It: Leave a comment (e.g., "I'd like to work on this!") so we can assign it to you.
- Fork & Clone: Fork the repository and clone it to your machine (
git clone https://github.com/<your-username>/Pact_OS.git). - Create a Branch: Create a descriptive branch (
git checkout -b fix/issue-12-typo). - Make the Change: Edit the single specified file following the issue instructions.
- Verify Locally: Run
npm run lint,npx tsc --noEmit, andnode scratch/run-tests.mjs. - Open a Pull Request: Push your branch and open a PR linking your issue (e.g.,
Closes #12). - Celebrate & Iterate: Our automated CI and maintainers will review and guide your PR to merge!
Start with our step-by-step Beginner's Contribution Guide for a comprehensive zero-to-PR walkthrough explaining Git forks, branch setup, making changes, and opening your first pull request.
Explore our curated issues:
- 🎯 Live Good First Issues — Filter active beginner-friendly tasks on GitHub.
- 📋 Curated Beginner Issues Factory — Canonical catalog of structured, self-contained Good First Issues across all PACT modules.
- 💬 Community Discussions — Ask questions, share ideas, and connect with other contributors.
All contributions are welcome! Whether you are optimizing SQL queries, refining accessibility, expanding test coverage, or implementing integrations:
- Review the canonical CONTRIBUTING.md developer guidelines.
- Ensure your changes adhere to Conventional Commits.
- Validate that all quality gates pass locally before opening a Pull Request.
| Resource | Purpose |
|---|---|
| 📖 Contributing Guide | Standard developer workflow, code style, and PR standards |
| 🌱 Beginner's Guide | Step-by-step zero-to-PR walkthrough for first-time contributors |
| 🎯 Beginner Issues Factory | 20 curated, actionable Good First Issues (#52–#71) |
| 💬 Discussions Guide | Categories, idea lifecycles, and community forum guidelines |
| 🏷️ Label Taxonomy | Official issue classification system and difficulty tiers |
| ⚙️ CI Pipeline | GitHub Actions quality gates and verification requirements |
| 🤝 Code of Conduct | Community standards and participation expectations |
| 🔒 Security Policy | Responsible disclosure of security vulnerabilities |
PACT is composed of 14 integrated systems operating under a cohesive, responsive interface:
| System | Capabilities | Status |
|---|---|---|
| Command Center | Daily situational dashboard with a photorealistic 3D celestial hero, focus metrics, and universal search (Cmd+K). |
Available |
| Tasks & Backlog | Priority matrix, estimated duration, scheduled times, deadline tracking, and multi-select bulk operations. | Available |
| Planner | Day, Week, and Month time-blocking with drag-and-drop scheduling, timezone boundary enforcement, and calendar conflict markers. | Available |
| Goals & Milestones | Strategic long-term intentional targets with progress tracking, associated projects, and target deadlines. | Available |
| Projects | Scoped deliverable containers grouping associated tasks, tracking phase completion rates and deadlines. | Available |
| Accountability Engine | Enforceable contracts binding tasks to confidential consequences, waiver quotas (max 2/week), and resolution workflows. | Available |
| Deep Work Focus Timer | Configurable interval focus engine (Pomodoro/Flow), synthesized Web Audio acoustic chimes, and deep work logs. | Available |
| Habits & Routines | Daily routine templates (Morning Kickoff, Evening Wind-down), completion tracking, and streak engines. | Available |
| Finance & Cash Flow | Integer-cents transaction ledger (amount_cents), recurring expense models, net cash calculations, and budget ceiling alerts. |
Available |
| Weekly Review | 5-step guided Sunday planning ritual: Celebrate Wins, Review Metrics, Process Incompletes, Calibrate Goals, Commit Next Week. | Available |
| Analytics & Scoring | Quantitative follow-through scoring, task completion velocity, weekly trend comparisons, and historical breakdowns. | Available |
| Integrations & Proofs | Connectors for Google Calendar (OAuth bi-directional sync), GitHub (commits/PRs), LeetCode, and Codeforces. | Available |
| Autonomous Sweeper | Autonomous cron engine (/api/cron/sweep-deadlines) evaluating grace periods, expiring overdue tasks, and escalating consequences. |
Available |
| Settings & Portability | User profile configuration, timezone management, notification channels, and complete RFC 4180 ZIP/JSON/CSV account export. | Available |
PACT features a distinctive luxury visual language designed for calm, executive focus:
- Obsidian Canvas Foundation: Deep OLED Obsidian (
#050505,#070707,#090909) eliminating interface fatigue. - Solid Luxury Surfaces: Rich card surfaces (
#0C0C0F,#101012) with ultra-fine specular hairline borders (rgba(255, 255, 255, 0.06)). - Restrained PACT Gold: Warm gold accents (
#D4AF37,#E6C34A) applied with surgical discipline for active states, progress indicators, and specular crescent highlights. - 3D Celestial Planetary Hero: Volumetric SVG radial illumination, Rayleigh atmospheric back-scatter, and razor-thin gold crescent lighting.
For complete guidelines, typography scales, and token values, see the Design System Specification.
PACT enforces a strict database-first, server-authoritative architecture:
+-------------------------------------------------------------+
| Client Layer (React 19 / UI) |
| - Obsidian Theme Tokens - 3D Celestial Planetary Hero |
| - Accessible Dialogs - URL State Sync (useUrlState) |
+-------------------------------------------------------------+
|
Server Actions & API Routes
|
+-------------------------------------------------------------+
| Domain Business Logic (src/lib/) |
| - Accountability Engine - Focus Session Engine |
| - Financial Arithmetic - Habits & Streak Engine |
| - External Proof Sweeper - Analytics Matrix |
+-------------------------------------------------------------+
|
Supabase SSR Database Client
|
+-------------------------------------------------------------+
| Database Layer (PostgreSQL) |
| - Row Level Security (RLS) on 100% of User Tables |
| - Confidential Consequence Masking |
| - Autonomous pg_cron Deadline Sweeper Engine |
+-------------------------------------------------------------+
For deep architectural details, see the Architecture Guide and Data Model Specification.
Pact_OS/
├── .github/ # Workflows (CI, audit), issue templates, Dependabot config
├── src/
│ ├── app/ # Next.js 16 App Router pages & API routes
│ │ ├── (auth)/ # Landing, login, and registration screens
│ │ ├── app/ # Authenticated Core OS routes (planner, goals, tasks, etc.)
│ │ └── api/ # Cron sweeper & data export API endpoints
│ ├── components/ # Reusable UI primitives (buttons, modals, cards)
│ ├── features/ # Feature modules (dashboard, calendar, habits, review)
│ ├── hooks/ # Custom React hooks (useUrlState, useSelection)
│ ├── lib/ # Core domain business logic and calculation engines
│ └── types/ # TypeScript domain schemas and contracts
├── supabase/ # PostgreSQL schema migrations and RLS security policies
├── tests/ # Automated domain and security test suites
├── docs/ # Comprehensive technical & product documentation
└── scratch/ # Test runner, secret scanner, and validation scripts
- Frontend Framework: Next.js 16 (App Router, React Server Components, Server Actions) & React 19
- Language: TypeScript 5 (Strict Mode)
- Styling: Tailwind CSS v4 & Vanilla CSS Design Tokens
- Motion & Icons: Framer Motion & Lucide React
- Database & Auth: Supabase PostgreSQL with Row Level Security (RLS) & SSR Cookie Auth (
@supabase/ssr) - Data Validation: Zod Schemas for all Server Actions and API payloads
- Audio Engine: Native Web Audio API synthesis (zero external audio dependencies)
Comprehensive technical specifications, system architectures, and operational runbooks are maintained in docs/:
| Document | Purpose |
|---|---|
| 🌱 Beginner Contributing | Step-by-step zero-to-PR guide for first-time contributors |
| 🎯 Curated Beginner Issues | Factory of 20 fully specified Good First Issues (#52–#71) across all PACT modules |
| 🏭 Issue Factory Architecture | 15-part issue specification, SEO discovery rules & domain vocabulary |
| 💬 Community Discussions | GitHub Discussions categories, ideas lifecycle, and contributor journey |
| 🏷️ GitHub Labels | Canonical issue classification, difficulty levels & composition |
| 🤖 Automation & Bot Architecture | Event-driven triage bot, security model & lifecycle policies |
| 🌐 GitHub Metadata | Canonical repository description, topics taxonomy & social preview |
| 🔧 Troubleshooting | Practical fixes for common setup, build, and Git roadblocks |
| 🌟 Master Documentation | Central comprehensive technical and product reference |
| 📖 Product Vision | Vision, dual taglines, product philosophy, and core principles |
| 📋 Feature Inventory | Authoritative inventory of all 14 core product modules |
| 🏗️ Architecture | Next.js 16 App Router architecture, server boundaries, and data flow |
| 🗄️ Data Model | Relational entity schemas, constraints, indexes, and RLS policies |
| 🔌 Integrations | Google Calendar, GitHub, LeetCode, and Codeforces connectors |
| 🔒 Security Architecture | 28-point security matrix, zero-trust validation, and secret sanitization |
| 🛡️ Threat Model | Threat actor matrix, attack surfaces, and defense-in-depth mitigations |
| 💻 Developer Guide | Local environment setup, database migrations, and development commands |
| 🧪 Testing Strategy | Automated test matrix and verification runbooks |
| ⚙️ CI Pipeline | GitHub Actions automated quality gates, secret scans & test matrix |
| 🛡️ Dependency Security | Dependency health, supply-chain hygiene & vulnerability policy |
| 📦 Release Management | Semantic Versioning policy, Keep a Changelog governance, and release checklists |
| 🌿 Git Workflow | Conventional Commits, branch hygiene, and pre-commit safety rules |
| 🗺️ Product Roadmap | Verified implementation status and future planned milestones |
| 🎨 Design System | Luxury Obsidian & Gold palette, 3D celestial planetary hero, and design tokens |
| 🔄 User Flows | Domain hierarchy flow, daily planning, and consequence lifecycle |
| 🚀 Deployment Runbook | Production cloud deployment guide and environment configuration |
PACT OS is free, open-source software built by developers who value intentionality, focus, and high-craft software engineering. We actively welcome contributions from developers, writers, designers, and students of all experience levels!
- 📖 Contributing Guide — Comprehensive workflow, branching, and PR policies
- 🚀 Beginner's Contribution Guide — Step-by-step zero-to-PR walkthrough
- 🎯 Curated Good First Issues — 20 self-contained, validated micro-tasks (5–30 min)
- 🏷️ Label Taxonomy — Standardized 12-label open-source taxonomy
- 🔧 Troubleshooting Guide — Solutions for common setup and build issues
- 💬 Community Discussions — Feature ideas, Q&A, and project showcases
PACT is built with care by an open-source community dedicated to personal mastery, high-integrity engineering, and intentional productivity.
A huge thank you to everyone who has contributed to PACT OS!
👉 View all contributors on GitHub • Contributors Hall of Fame
PACT is open-source software licensed under the MIT License.
Plan. Track. Improve. Repeat.