登录

potpie

potpie-aiApache-2.0活跃维护

为 AI 原生软件开发生命周期构建上下文图谱，把代码库和开发流程知识组织成可检索的图结构，让 AI 代理更准确地理解项目上下文。

Context Graph for AI Native SDLC

v2.0.1发布于 2026-08-31 09:46 UTC5,795star +5 / 7 天696fork同步于 2026-11-10 17:36 UTC
上下文图谱知识图谱AI代理软件开发生命周期RAG
对比 GitHub 官网agentsai-agentsai-agents-frameworkartificial-intelligencecontext-graph

怎么上手

由 README 提炼，执行前请确认
原文 
uv tool install potpie
potpie setup
硬件要求按 README 说明

README 未说明

下载：源码 zip·GitHub Releases（安装包）本站不镜像安装包

项目说明

由 README 自动翻译提炼
没人工点评？写下你的经验

把代码库和研发流程索引成上下文图谱，让 AI 编码代理带着项目背景干活

为 AI 原生软件开发生命周期构建上下文图谱，把代码库和开发流程知识组织成可检索的图结构，让 AI 代理更准确地理解项目上下文。

核心能力

  • 索引代码结构、决策、提交历史与团队知识构建上下文图谱
  • 用 potpie resolve 按任务拉取代理执行前应读的上下文
  • 用 potpie search 检索文件、工作流、缺陷与约定
  • 用 potpie record 写入可复用的项目经验
  • 向 Claude Code、Codex、Cursor 等编码工具安装技能

容易踩的坑

推荐用 uv tool install 安装，避免全局改动 Python 包；setup 向导会启动本地守护进程并生成默认 pot，需先完成才能用其他命令；GitHub、Linear 等集成需单独登录授权

内容由模型根据 README 生成，可能不完整或不准确，以官方文档为准。看原文 README

最近发版

5 个版本v2.0.1
全部 release
  1. v2.0.1最新正式版2026-08-31 · 2026-08-31 09:46 UTC

    v2.0.1

    Potpie v2.0.1 strengthens the local-first Potpie architecture with a unified Context Engine runtime, cleaner CLI and daemon boundaries, a public context-graph runtime, and more reliable local agent workflows.

    This release also publishes potpie-context-engine v0.2.0, consolidating the Context Engine under the potpie_context_engine namespace and introducing typed contracts for local and daemon execution.

    Highlights

    Unified Context Engine runtime

    Potpie now uses one importable Context Engine, one Potpie-owned resource manager, and matching typed contracts for in-process and daemon execution. The daemon lifecycle has been consolidated around the canonical python -m potpie.daemon runtime, replacing the older reflective host and RPC architecture.

    Public context graph and reconciliation

    This release introduces the public graph runtime and asynchronous reconciliation flow, alongside improvements to graph reads, views, ranking, entity re-typing, semantic search, and the graph workbench command surface.

    CLI and integration improvements

    The CLI and daemon now live within the root potpie package. The release adds GitLab and GitBucket integration support, improves structured JSON errors and exit codes, clarifies repository and pot resolution, and removes unsupported legacy service and ingestion commands.

    Packaging and security

    Potpie v2.0.1 supports Python 3.12, 3.13, and 3.14. The exact release artifacts were built once, smoke-tested on macOS and Linux, published to PyPI, and verified by filename and SHA-256 hash.

    The release also includes dependency and security hardening across aiohttp, cryptography, GitPython, MCP, Pillow, postcss, pydantic-ai-slim, pyasn1, setuptools, torch, and related dependency metadata.

    Install

    uv tool install potpie==2.0.1

    Or with pip:

    python3 -m pip install --user potpie==2.0.1

    Migration notes

    • The standalone potpie-context-core package has been removed.
    • Context Engine library imports now use the potpie_context_engine namespace.
    • Legacy reflective host/RPC surfaces have been removed.
    • Unsupported potpie service commands and pot-level Jira/Linear ingestion commands have been removed.
    • Destructive graph import and repair operations now require confirmation; automated usage can pass --yes.

    What's Changed

  2. v2.0.02026-07-03 · 2026-07-03 12:04 UTC
    查看更新说明

    Potpie v2.0.0

    Potpie v2.0.0 introduces the new local-first Potpie architecture: a packaged CLI, local context engine, daemon workflow, and agent-facing context graph designed for installation and use outside the development repository.

    This release makes Potpie’s context graph available through the main potpie package and the potpie-context-engine package, giving users a cleaner way to install, set up, and validate local repository context, CLI workflows, and agent integrations.

    Highlights

    Local Context Engine and CLI

    Potpie v2 ships the foundation for the local context engine, including a packaged daemon workflow, improved setup and authentication flows, GitHub login handling, root CLI version support, and installability through uv tool install potpie.

    Agent Runtime and Context Graph

    The release strengthens agent workflows with Potpie skills, agent-facing context graph support, a graph workbench command surface, graph explorer UI, and improved read-surface and domain contracts for context-engine usage.

    Integrations

    Potpie v2 expands context-graph integrations with Linear and Jira ingestion, executable diff-sync skills, GitHub and Linear OAuth packaging support, and improved flow through Pot creation with agent harness skills.

    Cleanup and Platform Direction

    Potpie v2 deprecates older server, library, UI-submodule, scanner-ingest, and dead context-engine surfaces that are no longer part of the OSS direction. It also includes dependency, CVE, Vanta, credential-storage, and auth hardening work.

    Potpie v2.0.0 is the stable release of the v2 line, intended for users and contributors to install Potpie directly, run the local context engine, and use the new CLI and context graph as the foundation for local agent workflows.

    What's Changed

  3. v2.0.0b3pre-release2026-06-24 · 2026-06-24 17:14 UTC
    查看更新说明

    Potpie v2.0.0b3 Beta

    This is the first beta release of Potpie v2 on PyPI.

    This release publishes potpie==2.0.0b3 as the main package and potpie-context-engine==0.1.0b3 as the context engine package. The goal of this beta is to make the new Potpie CLI, local daemon, and context graph available for installation and testing outside the development repository.

    This is a beta release, not a stable production release. It is intended for early users and contributors to validate installation, setup, local context graph behavior, CLI workflows, and agent integration before the stable v2 release.

    Use it via uv:

    uv tool install potpie

    Summary

    • Publishes the first beta potpie package to PyPI.
    • Publishes the first beta potpie-context-engine package to PyPI.
    • Introduces the packaged local context engine and daemon workflow.
    • Provides the foundation for the new Potpie CLI and agent-facing context graph.
    • Leaves detailed changes, PRs, and contributors to the generated changelog below.

    What's Changed

  4. v2.0.0b1pre-release2026-06-18 · 2026-06-18 12:00 UTC
    查看更新说明

    v2.0.0b1 Pre-release

    This pre-release introduces the foundation for Potpie v2: a local-first context engine, cleaner CLI and daemon workflows, stronger agent runtime support, faster indexing, deeper observability, and expanded context-graph integrations.

    The release is intended for early validation of the new architecture before the stable v2.0.0 release. It also starts removing older server, library, and UI-submodule pieces that are no longer part of the OSS direction.

    Highlights

    Local Context Engine and CLI

    • Introduced the local context engine foundation.
    • Added the Potpie skills manager for CLI-driven agent workflows.
    • Restored detached context-engine daemon lifecycle support.
    • Improved CLI authentication UX, setup flow, and GitHub login handling.

    Agent Runtime and Debugging

    • Added optional durable agent runtime support through Hatchet.
    • Routed regenerate flows through backend selection.
    • Added a VS Code DAP debug loop with a hypothesis-driven workflow.
    • Added Potpie skills to selected agents.

    Context Graph and Integrations

    • Added one-shot Linear team ingestion.
    • Added one-shot Jira project ingestion.
    • Added Jira/Linear integration with executable diff-sync skills.
    • Completed flow through Pot creation with agent harness skills and multiple integrations.

    Observability, Analytics, and Reliability

    • Added the new logging, Sentry, and Logfire observability package.
    • Switched the codebase to the new logging package.
    • Added Sentry support for CLI and daemon errors.
    • Added Sentry metrics and PostHog CLI usage instrumentation.
    • Fixed context-engine CI regressions and daemon lifecycle issues.

    Cleanup, Security, and Platform Direction

    • Deprecated the legacy server and related components.
    • Removed the Potpie library and Potpie UI submodule.
    • Added faster indexing and search capabilities using FFF.
    • Shipped security, Vanta, dependency, and auth hardening updates.

    What's Changed

  5. v1.1.12026-05-20 · 2026-05-20 11:30 UTC
    查看更新说明

    v1.1.1

    This release candidate focuses on improving the developer experience around @ file mentions and fuzzy file search. The main change is the backend foundation for fetching repository file structure before repo initialization. This supports a faster and more reliable @ file search experience, where users can type @ and fuzzy search file or directory names for mentions. The implementation is designed to work from local bare repositories and Git refs, avoiding GitHub API limits and making it suitable for very large repositories.

    Key Changes

    1. Improved @ file fuzzy search foundation

    • Added support for fetching complete repository file structure from a local bare git repo.

    • Supports refs such as branches, tags, and commit SHAs.

    • Returns structured file metadata including path, type, mode/SHA-related data, and hierarchy information.

    • Designed to support fast fuzzy search for file and directory mentions when users type @.

    • Avoids GitHub API tree limits by using local git data instead of network-based file fetching.

      Primary PR:

      • #764: Add file index before repo initialization
    1. Security and compliance updates: This release also includes Vanta vulnerability remediation across multiple severity levels. Related PRs:
      • #766: fixed med vanta vulnerabilities
      • #770: fixed critical, high, medium, and low Vanta vulnerabilities
      • #773: fixed all Vanta vulnerabilities
      • #779: fixed high and medium Vanta vulnerabilities
      • #784: resolved high and medium vulnerabilities
      • #788: fixed medium Vanta vulnerabilities
    2. CI stability: Repaired CI failures after the context-engine merge. Related PR:
      • #765: fix(tests): repair CI failures after context-engine merge

    PR summaries

    Full Changelog: https://github.com/potpie-ai/potpie/compare/v1.1.0...v1.1.1

用户点评

登录用户的真实使用记录，可按版本和硬件筛选
共 0 条

    还没有人点评。第一个说出真实体验的人最有价值。

    README 原文

    未翻译
    在 GitHub 打开

    Potpie turns your codebase and software development lifecycle into a living context graph for AI agents. It indexes code, structure, decisions, source history, team knowledge and engineering workflows, so agents can answer questions, plan changes, debug failures, and write code with project-specific context.

    Potpie context graph demo

    Install and setup Potpie

    Step 1: install the CLI through PyPI with uv or pip:

    uv tool install potpie

    or:

    python3 -m pip install --user potpie

    [!NOTE] uv tool install potpie is recommended for CLI installs because global mutation of Python packages is generally not recommended.

    Step 2: Run the Potpie setup wizard

    potpie setup

    The setup wizard provisions local config, storage, the daemon, a default pot, and agent skills. It also lets you choose integrations and the coding harness Potpie should configure.

    Potpie setup wizard

    Step 3: Open your configured harness

    Potpie is already integrated into your selected harness. You can start using Potpie with the repo of your choice.

    Open your previously selected harness and ask it to use Potpie for the repo. Potpie in OpenAI Codex

    [!NOTE] You don't need to run a separate manual ingest command. The CLI registers sources and the configured agent can ingest or update project context when the task requires it.

    You can view your context graph in the web UI:

    potpie ui

    This will open a graph explorer in your browser. Potpie web UI

    Basic CLI user checklist

    The main CLI commands are:

    CommandPurpose
    potpie setupRun first-time local setup for config, daemon, default pot, and agent skills.
    potpie loginSign in to Potpie for account-backed and managed features.
    potpie github login / potpie linear loginConnect source integrations you want agents to use.
    potpie statusShow context readiness for the active pot, including daemon, graph, and skill checks.
    potpie auth statusShow configured integration auth status.
    potpie auth status --verifyVerify integration credentials with lightweight API checks.
    potpie doctorRun local diagnostics for daemon, backend capabilities, and skill drift.
    potpie source add repo .Register the current repo as a source for the resolved pot.
    potpie pot list / potpie pot use <id-or-name>List pots and choose the active workspace.
    potpie resolve "<task>"Pull the context an agent should read before doing a task.
    potpie search "<query>"Look up a specific file, workflow, bug, decision, or convention.
    potpie record --type <type> --summary "<summary>"Write a durable project learning.
    potpie graph ...Use lower-level graph reads, quality checks, proposals, and commits.
    potpie uiOpen the local graph explorer served by the daemon.
    potpie skills install --agent <agent>Install or refresh Potpie guidance for an agent harness.

    Examples:

    potpie setup --repo . --agent claude
potpie github login
potpie auth status
potpie status
potpie source add repo .
potpie resolve "what should I know before working in this repository?"
potpie search "authentication flow"
potpie record --type decision --summary "Prefer the Potpie CLI for graph work"

    You can find an exhaustive list with more examples in our docs.

    Integrations and Coding Harnesses

    Potpie supports a variety of integrations and coding harnesses, with more coming. If your team needs a new integration or harness, please raise a ticket.

    Integrations

    ToolDescription
    GitHubIndex repositories, pull requests, issues, reviews and source history.
    LinearIndex teams, issues, projects and documents.
    JiraIndex projects, issues, status and changelog context.
    ConfluenceIndex spaces, pages, runbooks and decisions.

    Coding harnesses

    ToolDescription
    Claude CodeInstall Potpie instructions and skills for Claude Code.
    OpenAI CodexInstall Potpie instructions and skills for OpenAI Codex.
    CursorInstall Potpie instructions and skills for Cursor.
    OpenCodeInstall Potpie skills for OpenCode.

    Architecture

    Potpie's current architecture is CLI-first. CLI is designed to be used by both humans and agents. Read the deeper architecture notes in docs/context-graph/architecture.md.

    License

    This project is licensed under the Apache 2.0 License. See LICENSE.

    Community & Support

    • GitHub Issues: bugs and repository-scoped requests
    • Discord: community discussion and support
    • Docs: setup, product guides, and integration details

    New contributions are always welcome. Read the Contributing Guide to set up your environment, understand the workflow, and open a pull request.

    相关项目

    同分类里 star 最高的项目
    对比全部 →
    ECC
    affaan-m·JavaScript

    为 Claude Code、Codex、Cursor 等编码智能体提供技能、直觉、记忆与安全防护的性能优化层，让 AI 编程助手更稳定高效地干活。

    智能体框架+4Agent 框架
    300641+191444kv2.2.32026-11-09 04:56 UTC
    deepseek-harness
    deepseek-ai·TypeScript

    DeepSeek 开源的 Agent 编排框架，把模型、工具、记忆等所有能力都做成可插拔插件，方便按需拼装和扩展智能体。

    Agent 框架+3Agent 框架
    278086+288634kdsh-v0.2.2-rc.12026-11-04 13:06 UTC
    hermes-agent
    NousResearch·Python

    一个可随使用不断成长的 AI Agent 框架，支持接入 Claude、ChatGPT 等多种大模型，用于搭建和编排自主智能体。

    Agent 框架+3Agent 框架
    262361+108159kv0.23.02026-11-10 17:13 UTC
    firecrawl
    firecrawl·TypeScript

    把任意网页抓取并转成干净 Markdown 或结构化数据，直接喂给 LLM 和 AI Agent，省去自己写爬虫和清洗的麻烦。

    网页抓取+4Agent 框架
    200422+108311kv2.11.02026-11-10 17:12 UTC