Pritha

A local-first, Codex-native agent foundry and knowledge OS.

Pritha turns an idea, project, dataset, or workflow into a reviewed, testable specialist-agent project. It combines a contract-driven agent lifecycle with a curated Markdown knowledge base, so agent-building decisions remain inspectable and reusable.

The primary workbench is a Codex task opened on this repository. The local Control Center and its Voice interface are active, functional operator surfaces, but they are optional: you do not need either one to start using Pritha.

Pritha is local-first and currently in active beta.

Start In Codex

1. Download or clone this repository.
2. Open the Pritha folder in Codex.
3. Say:

Set up and start Pritha.

Codex reads the repository instructions and performs the safe local bootstrap for you. “Start” means Pritha is ready to use in the current Codex task; it does not silently start a web server or install a background service.

The manual equivalent is:

node scripts/bootstrap.mjs prepare --profile local

That command prepares local dependencies, rebuilds the generated memory index and embeddings from tracked Markdown, and verifies semantic memory. It does not install credentials, Tailscale, launchd, cron, or another durable service.

What Pritha Is

Pritha has two connected jobs:

• Agent foundry: design, research, scaffold, test, hand off, and evolve focused child agents with explicit contracts and operating boundaries.
• Knowledge OS: turn source material and implementation evidence into reviewed briefs, assessments, decisions, standards, workflows, and reusable agent-building knowledge.

Pritha is not a hosted SaaS, a public multi-user service, or one monolithic assistant with unrestricted access. It does not trust raw input or repository candidates automatically, install discovered code during research, or enable external access and long-running services without an explicit operator action.

The current release is Codex-native. Other coding-agent runtimes may be explored through future adapters, but are not presented as implemented compatibility.

What You Can Do

In the Codex task, ask Pritha to:

• create a specialist agent for a project or workflow;
• review a link, file, idea, or technical approach;
• turn useful evidence into a brief, review, decision, or standard;
• inspect, test, or improve an existing child-agent project;
• compare a proposed change with Pritha's accepted baselines and knowledge.

For example:

Create an agent that reviews research links and reports only meaningful changes.

Pritha will guide the contract and research steps before creating a production scaffold. The CLI fallback for the same interview is:

node scripts/pritha.mjs interview

For an autonomous agent build, the contract and the user-visible Outcome Spec are reviewed separately. The interview proposes a 1,000,000 build-token budget and requires the user to confirm or change it before an accepted autonomous contract can enter delivery. Legacy accepted contracts use the same default.

Outcome-Driven Delivery

The canonical delivery sequence is:

outcome init → outcome approve → deliver → delivery accept

node scripts/pritha.mjs outcome init <accepted-contract-path>
node scripts/pritha.mjs outcome approve <outcome-spec-path> --approved-by user
node scripts/pritha.mjs deliver <outcome-spec-path> --project <clean-git-project>
node scripts/pritha.mjs delivery accept <run-id> --accepted-by user

Delivery compiles the approved Outcome Spec into immutable Trials, implements inside a disposable pritha/build-* Git worktree, and independently records revision-bound evidence. verified means the machine-verifiable Trials passed; it is deliberately distinct from the user's accepted decision. A delivery worktree is never merged, pushed, or deployed automatically.

The source project must be clean before a disposable worktree is created. Dirty delivery worktrees are preserved for inspection and are never force-removed. Missing runtime, isolation, Goal, evidence, or budget capabilities produce typed blockers instead of silently weakening the run. Codex build turns use an ephemeral thread with a bounded Goal and the remaining confirmed token budget. If the installed Codex lacks Goal support, only the user may authorize one explicit turn without it; retry after upgrade and abandon remain available.

A trusted local Trial backend proves only that the command passed on the local host. It is not evidence of sandbox isolation. Contracts that require isolation must use a backend whose capability probe confirms that boundary.

Core And Optional Surfaces

Layer	Includes	Required to start?
Core	Codex workbench, repository instructions, contracts, curated Markdown, local generated memory, scaffold/tests/reports	Yes
Functional operator layer	Control Center with Agents, Voice, Settings, and diagnostics	No
Additional opt-in surfaces	Tailscale private access, Telegram, hosted model calls, web integrations, deployment and services	No

Optional means that a surface is not required for the core Codex workflow. It does not mean that Control Center or Voice is experimental or unfinished.

How It Works

user intent or material
→ Codex + Pritha repository rules
→ accepted agent contract + separately approved Outcome Spec
→ gated memory, external-source, and repository research
→ disposable-worktree implementation + immutable Trials
→ verified evidence → explicit user acceptance
→ scaffold, handoff, lifecycle reports, and instance-local registry updates

Authored Markdown is the source of truth: platform knowledge is tracked, while live child-agent documents remain in instance-local state. SQLite, FTS, relations, and embeddings are generated local indexes rebuilt from those allowed sources. See Architecture for the system boundaries.

Child-agent contracts, Outcome Specs, research, lifecycle reports, profiles, and registries are runtime state of exactly one Pritha instance. They live under PRITHA_STATE_ROOT/agents/ (or the ignored .private/agents/ compatibility fallback), are not published through GitHub, and are never copied between Pritha instances. Tracked 11_agents/ is a historical/reference platform layer, not a live child-agent registry.

Optional Control Center And Voice

To prepare and start the local Control Center:

node scripts/bootstrap.mjs --profile local --start control-center

The active Control Center provides /agents, /voice, /settings, and read-only diagnostics. Its integrated Voice surface supports realtime operator work and can route deeper tasks to Codex. Some Voice and hosted-model features require explicit credentials and can incur provider costs.

The start command runs the UI in the foreground on localhost. It does not install launchd, cron, Tailscale, credentials, or a durable service. Private access from another trusted device is a separate, operator-approved Tailscale workflow.

Security

Pritha is active-beta software for a trusted, single-user machine. The Control Center is a privileged local service: it can route work to Codex, read project files, and manage local credentials. Treat access to it as privileged access to your machine.

• Run it on localhost, or behind Tailscale with devices you own and trust.
• Do not expose it through 0.0.0.0, LAN binding, a public reverse proxy, or Tailscale Funnel.
• Never commit real secrets from .env* or private runtime state.
• Treat links, files, transcripts, and voice input as untrusted. Raw input must not directly control tools, memory promotion, deployment, or publishing.
• Report vulnerabilities privately according to SECURITY.md, not in a public GitHub Discussion.

Documentation

• Getting Started
• Architecture
• Using Pritha
• Memory
• Control Center
• Realtime and Voice
• Operations
• Prerequisites
• Troubleshooting
• Contributing

Quality

For implementation changes, run:

node scripts/quality-gate.mjs

License

MIT. See LICENSE.