Ptah

What is Ptah about?

Ptah provides a provider‑agnostic AI development environment that analyses a repository, builds a searchable map of its architecture, and runs a team of context‑aware agents to perform code generation, review, testing, and automation. The experience is available as a native Electron desktop app, a VS Code sidebar/webview extension, and a headless CLI.

How to use Ptah?

Desktop app

1. Download the installer from the official site and install.
2. Open a workspace folder.
3. Run Setup → Workspace Analysis to scan the project and generate a tailored agent team.
4. Start a chat session or open Thoth to configure memory, schedules, and messaging gateways.

VS Code extension

1. Install "Ptah — The Coding Orchestra" from the VS Code Marketplace.
2. Click the Ptah icon in the Activity Bar.
3. Add AI providers in the settings panel.
4. Run the setup wizard to create agents and skills.

CLI

npx @hive-academy/ptah-cli init --human   # interactive setup
npx @hive-academy/ptah-cli doctor          # verify installation
npx @hive-academy/ptah-cli session start --task "explain this repo"

The CLI works in CI pipelines, scripts, or any headless environment.

Key features of Ptah

• Persistent hybrid memory (BM25 + vector search) with reciprocal‑rank fusion for fast natural‑language symbol lookup.
• Tree‑sitter AST indexing for JavaScript, TypeScript, Python, and Go, providing precise file positions for every symbol.
• Sub‑agent orchestration: a main coordinator spawns specialist agents (architect, backend, frontend, tester, reviewer) each with independent model, provider, and context window.
• Orchestra Canvas: up to nine concurrent sessions displayed in a draggable grid.
• Tribunal: multi‑vendor review panels where one model writes code, another reviews, and a third adjudicates.
• Skill synthesis: successful execution trajectories are extracted into reusable skill files.
• Cron scheduler (SQLite‑backed) for nightly security scans, weekly dependency checks, or automated ticket processing.
• Messaging gateways: trigger and approve work from Telegram, Discord, or Slack, with per‑thread context.
• Built‑in MCP server exposing the ptah_* tool catalog (workspace analysis, LSP diagnostics, AST queries, symbol search, dependency graphs, browser automation, sandboxed code execution).
• Provider‑agnostic: supports Frontier SDKs, OpenRouter (200+ models), Ollama (local), and existing coding CLIs.
• Extensible plugins: install community‑built skills, workflow packs, or additional MCP servers.
• Cost & token tracking per session, model, and agent with exportable logs.

Use cases of Ptah

• Continuous codebase understanding: keep a searchable map of a large monorepo for onboarding new developers.
• Automated feature implementation: describe a feature in plain English; Ptah’s agents generate, test, and open a PR.
• Security auditing: schedule nightly runs that scan for vulnerable patterns and report via Slack.
• Cross‑model review: use a security‑focused model to review diff generated by a high‑throughput model.
• CI/CD integration: run the CLI in pipelines to execute MCP‑compliant tasks such as linting, dependency graph generation, or browser‑based UI testing.
• Custom tooling: expose internal tools through the MCP server and let external orchestrators drive them.

FAQ from Ptah

Q: Do I need an internet connection? A: Only when using remote model providers. Local models (Ollama) run fully offline.

Q: How are API keys stored? A: Keys are saved in the OS secure store (Keychain, Credential Manager, or secret‑service) and never leave the machine.

Q: Can I mix different model vendors in one session? A: Yes. Each sub‑agent can be assigned its own provider, allowing a security‑focused model to review code written by a faster model.

Q: Is there a way to pause or cancel an agent run? A: Agents expose tool calls in an execution tree; you can approve or reject each call from any connected gateway before it executes.

Q: How do I add my own plugins or skills? A: Use the plugin manager in the desktop app or VS Code extension, or drop a skill JSON file into the .ptah/skills/ folder; the system will validate hashes before loading.

Ptah — The Coding Orchestra

An AI dev team that learns your architecture and keeps shipping.

Persistent memory, a staffed team of agents, and always-on delivery — in a desktop app, a VS Code extension, and a headless CLI.

Website · Download · Documentation · VS Code extension

---

See it work

The video above is a real session, not a mockup. It shows memory recall, sub-agent fan-out, and scheduled runs.

Short feature clips:

Clip	Topic
Install	Install the desktop app on your platform
Sign in	Accounts, keys, and credential storage
Workspace analysis	Scan a repository and detect its stack
Agent generation	Generate a project-specific agent team
Agent orchestration	Spawn, monitor, and steer headless agents
Built-in MCP server	The ptah_* tool catalog and code execution
Model providers	Add providers, keys, and models
Plugins	Install skills and workflow packs

---

What Ptah is

Ptah is an AI development environment for real projects. It indexes your repository before the first message, keeps the decisions it makes after the last one, and runs a team of specialized agents against that shared map.

One core powers three surfaces:

Surface	What it is	Best for
Desktop app	Native app for Windows, macOS, and Linux	The complete product, including always-on runs
VS Code extension	Sidebar and full-panel webview	Work that stays inside the editor
CLI	Headless JSON-RPC 2.0 over stdio	CI pipelines, scripts, and agent-to-agent use

---

Three pillars

1. It knows your architecture

Ptah builds a map of your codebase and keeps it.

• Persistent memory — hybrid BM25 and vector search, fused with Reciprocal Rank Fusion. The agent that builds feature ten recalls the auth pattern from feature one.
• Tree-sitter indexing — structural AST parsing across JavaScript, TypeScript, Python, and Go. Every function, class, and import gets an exact file position.
• Hybrid symbol search — ask "where do we validate auth tokens" in plain English. Ranked, cited results go straight into agent context.

Read more: Memory · Workspace analysis

2. A staffed team, not a solo agent

• Sub-agent orchestration — a main agent delegates to specialists: architect, backend developer, frontend developer, tester, and reviewer. Each specialist can use its own provider, model, and context window.
• Orchestra Canvas — up to nine concurrent sessions in one drag-and-resize grid. Background agents continue while you review a single tile.
• Tribunal — put several vendors on one panel. One implements, a different one reviews the diff, and a third judges the disagreement.
• Skill synthesis — when a delivery pattern succeeds, Ptah extracts the trajectory, judges its quality, and promotes it to a permanent, shareable skill file.
• Execution tree — every tool call, sub-agent, token count, and cost, live.

Read more: Agents · Skill synthesis · Tribunal

3. It keeps shipping while you sleep

• Cron scheduler — SQLite-backed scheduled runs. Nightly security reviews, weekly dependency scans, or the next ticket in the backlog.
• Messaging gateways — trigger and approve agent work from Telegram, Discord, or Slack, with voice input. Discord keeps a separate agent context per thread.
• Approval relay — review every tool call and diff before it executes, from any connected gateway.

Read more: Automation

---

More capabilities

• Setup wizard — scans the workspace, detects the project type and frameworks, then generates agents, rules, and skills for that project.
• New project scaffolding — plan and scaffold a fresh Nx workspace with a generated roadmap and its own agent team.
• Built-in MCP server — a local server on loopback exposes the ptah_* tool catalog: workspace analysis, LSP diagnostics, AST analysis, symbol search, dependency graphs, browser automation, agent spawning, and sandboxed code execution.
• Stdio MCP server (ptah mcp-serve) — drive Ptah from any MCP-compliant host. External orchestrators can spawn, monitor, and steer agents, or delegate a whole task.
• Browser automation — navigate, click, type, read content, capture the network, take screenshots, and record sessions.
• Marketplace and plugins — install skills, workflows, and MCP servers. External installs need explicit consent bound to the resolved version and file hashes.
• Harness sync — one reconciler writes your agents, skills, and MCP intents into the harness folders of every supported AI tool.
• Tasks board — a six-column Kanban over the task specs in .ptah/specs/.
• Editor tools — Monaco diff view, integrated terminal, file tree, git status, and a commit composer.
• Cost and token tracking — per session, per model, and per agent, with history and export.

---

Providers

Ptah is provider-agnostic. Bring the vendors you already use:

• Frontier model vendors, through their own SDKs and OAuth sign-in.
• More than 200 models through OpenRouter.
• Local models through Ollama.
• Rival coding CLIs that are already installed on your machine, detected automatically and used as headless workers.

Keys stay on your machine, in the operating system secure store. Mix vendors so the model that reviews a security-sensitive diff is not the model that wrote it.

Read more: Providers

---

Get started

Desktop app

1. Download the installer for your platform from ptah.live/download.
2. Install and open the app.
3. Open a workspace folder.
4. Run the setup wizard from Setup → Workspace Analysis.
5. Start a session, or open Thoth to configure memory, schedules, and gateways.

VS Code extension

1. Install Ptah — The Coding Orchestra from the VS Code Marketplace.
2. Open the Ptah icon in the activity bar.
3. Add a provider in the settings panel.
4. Run the setup wizard.

CLI

npm i -g @hive-academy/ptah-cli

ptah init --human                          # guided setup on a terminal
ptah doctor                                # confirm the install is ready
ptah session start --task "explain this repo"

The CLI runs standalone. It does not need VS Code or the desktop app.

Read more: Getting started · CLI guide

---

Pricing

Ptah is free and open source under the MIT license. There is no trial and no credit card.

Ptah Builders is a paid membership for cohort sessions, private support, and community packs. The product itself stays free. Join the waitlist at ptah.live.

---

Development

Ptah is an Nx monorepo. The apps and libraries share one hexagonal core.

apps/          # desktop app, VS Code extension, webview, CLI, TUI,
               # license server, landing page, docs site, e2e suites
libs/backend/  # runtime-agnostic services; ports live in platform-core,
               # adapters in platform-vscode | platform-electron | platform-cli
libs/frontend/ # Angular 21 feature libraries (signals, OnPush)
libs/shared/   # the one bridge between frontend and backend
libs/api/      # NestJS libraries for the license server
libs/web/      # Angular libraries for the marketing site

git clone https://github.com/Hive-Academy/ptah-extension.git
cd ptah-extension
cp .env.example .env
npm install

npm run dev              # watch the extension and the webview
npm run electron:serve   # run the desktop app
npm run cli:dev          # run the headless CLI
npm run docs             # serve the documentation site
npm run landing          # serve the marketing site

npm run lint:all
npm run typecheck:all
npm run test
npx nx graph             # visualize the dependency graph

Architecture rules, coding standards, and per-project guides are in the instruction files at the repository root and in each app and library folder.

---

Contributing

Read CONTRIBUTING.md before you open a pull request. Report a security issue through SECURITY.md.

• Issues
• Documentation

---

License

MIT © Ptah Orchestra