Install Potpie with uv or pip for Claude Code and Codex

What Potpie installs and how it fits an AI coding workflow

Potpie turns a software project and its development context into a context graph that an AI agent can use while answering questions, planning changes, debugging problems, and working with project-specific conventions. Its current architecture is CLI-first: both people and agents interact with the command-line interface, while a local daemon provides the supporting runtime. The browser-based graph explorer is useful for inspecting the resulting context, but it is not the primary interface for every operation.

The normal workflow begins on the development machine. You install the potpie command, run its setup wizard, select a coding harness, and open that harness in the repository where you want to work. Potpie's setup provisions local configuration, storage, the daemon, a default pot, and agent skills. A pot is the workspace whose sources and context the agent resolves. You can then check readiness, register a repository when necessary, search context, resolve relevant information for a task, and record durable project learnings.

Potpie documents integrations with Claude Code and OpenAI Codex, as well as Cursor and OpenCode. This article concentrates on Claude Code and Codex because they match the installation intent, but the local installation and verification principles are the same for the other documented harnesses.

Prerequisites and decisions to make first

Potpie v2.0.1 documents support for Python 3.12, 3.13, and 3.14. That release was packaged and smoke-tested on macOS and Linux, but a smoke-test statement is not the same as a complete platform support matrix. Check the current Potpie release information if you are installing a version newer than v2.0.1, because supported Python versions and platform details can change.

You also need either uv or Python's pip installer. Potpie recommends uv tool install for CLI installation because it avoids globally mutating a Python environment. The documented pip alternative uses python3 -m pip install --user, which installs into the current user's Python environment rather than requiring a system-wide package mutation.

Have a source repository available if you want to configure and test Potpie against real project context. The setup wizard can be launched from a repository with documented repository and agent options, or it can guide you interactively. You should also decide which coding harness you intend to configure. If you need account-backed or managed Potpie features, the CLI includes potpie login. Source integrations such as GitHub and Linear have their own login commands and are separate from basic local installation.

Install Potpie with uv or pip

Potpie's documented installation has three core stages: install the CLI, run the setup wizard, and open the configured coding harness. The first stage has two supported package installation choices. Use one installation method, not both, unless you are intentionally testing separate environments.

Recommended installation with uv

If uv is already available in your environment, install Potpie as an isolated command-line tool:

uv tool install potpie

This is Potpie's recommended CLI installation route. Tool installation keeps the command's Python dependencies separate from the packages in a project environment, reducing the chance that installing a CLI changes an application's dependency set.

Alternative installation with pip

If you are using the documented pip route, run:

python3 -m pip install --user potpie

Calling pip through python3 -m pip makes the selected Python interpreter explicit. The --user option avoids a system-wide install. The exact directory used for user-level executables varies by Python distribution and operating system, so this guide does not prescribe a path. If installation succeeds but the shell cannot find potpie, inspect the installation messages and the user executable directory for the Python interpreter you invoked.

Pinning the documented v2.0.1 release

A normal unpinned installation requests the current package available from the configured package index. If you specifically need the documented v2.0.1 behavior, Potpie provides these pinned forms:

uv tool install potpie==2.0.1

Or with pip:

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

Pinning is useful when a team needs a reproducible version during evaluation or when following release-specific migration notes. Version 2.0.1 consolidated the CLI and daemon under the root potpie package, uses the canonical python -m potpie.daemon runtime internally, removed legacy service and ingestion commands, and moved Context Engine imports to the potpie_context_engine namespace. Do not use removed commands from older tutorials with that release.

Run the setup wizard and create the local environment

After installation, run the first-time setup:

potpie setup

Follow the interactive prompts and select the coding harness and integrations relevant to your workflow. The setup wizard is responsible for local configuration, storage, the daemon, a default pot, and agent skills. Because available choices can evolve, use the labels shown by the installed version rather than assuming that a screenshot from another release matches your environment.

Potpie also documents a non-default setup example that points at the current repository and identifies Claude as the agent:

potpie setup --repo . --agent claude

Run this command from the repository you intend the dot to represent. The dot means the current working directory, so changing directories before setup changes the repository passed to Potpie.

For OpenAI Codex, choose Codex through the setup wizard's supported harness selection. The available evidence confirms Codex support but does not establish a literal command-line value for --agent. We therefore do not guess one. Interactive selection is the safer documented path when an exact option value is not established.

Optional account and source integrations

Basic local setup and account-backed features are distinct concerns. Potpie provides the following sign-in command for account-backed and managed capabilities:

potpie login

If the repository context needs GitHub data, Potpie documents a dedicated integration login:

potpie github login

Potpie also documents potpie linear login for Linear. Connect only the integrations required by your workflow. Authentication to a source system gives Potpie access according to the credentials and permissions granted there, so use an appropriately scoped account and review access before connecting organizational repositories or issue data.

You can inspect configured integration authentication without making assumptions about whether every credential works:

potpie auth status

To perform lightweight API checks against configured integration credentials, use:

potpie auth status --verify

Use Potpie with Claude Code or OpenAI Codex

Once setup finishes, open the harness you selected and work from the intended repository. Ask the harness to use Potpie for that repository and begin with a bounded context request. Potpie's role is to help the agent retrieve repository-specific information instead of relying only on the text currently visible in the conversation.

Claude Code workflow

Claude Code is explicitly supported as a Potpie coding harness. You can select it in the setup wizard or use the documented setup example:

potpie setup --repo . --agent claude

After setup, launch Claude Code through its normal workflow from the project. The exact Claude Code installation and startup command is outside Potpie's own documented command set and can vary with that tool's distribution, so it is not invented here. Once Claude Code is open, ask it to use Potpie to establish context before changing code.

If agent guidance needs to be installed or refreshed later, Potpie provides:

potpie skills install --agent <agent>

Replace <agent> only with a value supported by your installed Potpie version. The documented setup example establishes claude for Claude. Do not infer other identifiers from display names.

OpenAI Codex workflow

OpenAI Codex is also listed as a supported coding harness. Select Codex when the setup wizard asks which harness to configure, then open Codex in the target repository using its normal supported workflow. Ask it to use Potpie before beginning the substantive task.

This distinction matters: Potpie's documentation establishes Codex integration, but the supplied evidence does not specify a Codex executable command or a literal Potpie --agent value. An installation guide should not turn an assumed identifier into a command that readers may copy. Let the setup wizard present the valid current choice.

Useful first context operations

Potpie provides direct CLI operations that are useful both for understanding the system and for isolating an issue from the coding harness. To ask what context should be read before work begins, run:

potpie resolve "what should I know before working in this repository?"

To search for a specific concept:

potpie search "authentication flow"

To save a durable project decision:

potpie record --type decision --summary "Prefer the Potpie CLI for graph work"

These commands provide a valuable diagnostic boundary. If direct CLI context operations work but the coding harness does not use Potpie, focus on the installed agent skills or harness configuration. If direct operations also fail, investigate the daemon, active pot, source registration, and graph readiness first.

Verify the daemon, pot, graph, skills, and integrations

Do not treat a successful package installation as proof that the complete system is ready. Installation only places the CLI in an environment. The setup wizard must still establish the local runtime, and the active pot must have the source and context required for useful answers.

Check overall readiness

Start with:

potpie status

This reports context readiness for the active pot, including daemon, graph, and skill checks. Read the complete output rather than looking only for one successful line. A running daemon does not necessarily mean that the intended repository is associated with the active pot or that useful graph context is available.

Run local diagnostics

If readiness is incomplete or behavior is inconsistent, run:

potpie doctor

The doctor command performs local diagnostics covering the daemon, backend capabilities, and skill drift. Skill drift is particularly relevant after upgrading Potpie or changing a coding harness because installed guidance may no longer match the current package.

Inspect and select the active pot

List the available pots:

potpie pot list

If the wrong workspace is active, select the intended pot by its displayed identifier or name:

potpie pot use <id-or-name>

Replace the placeholder with a value returned by your own installation. Pot identifiers and names are environment-specific and should never be copied from another user's output.

Register the current repository when needed

If the current repository is not registered as a source for the resolved pot, run this command from that repository:

potpie source add repo .

Then repeat potpie status and a small resolve or search request. This checks the local graph workflow independently of remote browser access.

Open the graph explorer and discover its actual local endpoint

Once status and diagnostics are satisfactory, open the graph explorer:

potpie ui

Potpie documents that this command opens the graph explorer in a browser and that the UI is served by the daemon. Observe the terminal output and the address opened by the browser. Record the complete local URL, including its scheme, host, and port if one is present.

The endpoint must be discovered from the running installation because the available documentation does not establish a stable hostname, port, URL scheme, or bind address for this guide. It also does not establish whether the graph explorer has built-in authentication. These are not minor omissions when remote access is involved. They determine what target Localtonet should reach and whether publishing the UI would expose sensitive information without an application login.

Local verification checklist

Before creating any tunnel, verify all of the following:

• The potpie ui command completes without reporting a daemon or graph error.
• A browser opens the graph explorer at the address reported by your installation.
• Refreshing that local address continues to load the application.
• The graph explorer corresponds to the intended pot and repository.
• The page behaves as expected while the Potpie daemon remains available.
• You have determined whether the UI requests authentication before displaying project data.

If the browser opens automatically but you miss the address, return to the terminal output associated with potpie ui. Do not select a guessed port simply because another local development tool commonly uses it. Likewise, do not assume the service is bound only to loopback or to every network interface. Use what the running process reports and what you can verify locally.

Expose the verified Potpie graph UI with Localtonet

After the UI works locally, an HTTP tunnel is the appropriate Localtonet family for a browser-based HTTP service. Our client runs on the machine that can reach the Potpie endpoint and establishes an outbound connection to a Localtonet relay server. The resulting tunnel provides a public HTTPS address without inbound router port forwarding, firewall changes, VPN setup, or a public IP address.

Creating a tunnel does not automatically mean it is running. The selected Localtonet client must be connected, and the tunnel must be started. The tunnel remains available only while that client or device is connected and the tunnel is running.

For the current dashboard workflow, consult our Localtonet HTTP tunnel documentation. Custom-domain DNS instructions should be checked against the current documentation before changing DNS because requirements can evolve.

Routine operations, upgrades, and safe tunnel management

Use status before beginning significant work

Run potpie status when switching repositories, changing pots, upgrading Potpie, or returning to an environment that has not been used recently. This catches a stopped daemon, incomplete graph state, or stale skills before the coding harness starts a large task with insufficient context.

Separate Potpie health from tunnel health

There are two independent service layers in this workflow. Potpie owns the local daemon and graph explorer. Localtonet owns the outbound tunnel that forwards requests to the selected local target. If the public URL fails, first determine whether the local UI still works.

Do not expose more than the UI endpoint

Configure the HTTP tunnel for the graph explorer's actual local IP address and port. Do not substitute a broad network service, administrative port, unrelated development server, or guessed daemon interface. If Potpie reports multiple endpoints, identify which one is specifically intended for browser access before creating the tunnel.

Keep device tokens private

A Localtonet authentication token identifies the client device that runs the tunnel. Treat it as a credential. Do not include it in commands shown in documentation, commit it to a repository, or send it in a public support issue. Server or region codes should also be selected from the current dashboard rather than embedded in reusable scripts without review.

Review exposure after upgrades

Potpie upgrades can change daemon behavior, UI behavior, dependencies, or local addresses. Version 2.0.1 itself consolidated runtime components and removed unsupported legacy surfaces. After an upgrade, rerun status and doctor checks, open the graph explorer locally, and verify its address before restarting an existing tunnel. Never assume that an old target remains correct.

Use temporary exposure when possible

The simplest risk reduction is to keep the tunnel stopped unless remote graph access is actively needed. The coding harness and Potpie CLI can continue to operate locally without a public graph explorer. Start the tunnel for a defined task, validate who needs the URL, and stop it afterward.

Troubleshooting common installation and remote-access problems

The shell reports that potpie is not found

Confirm that the installation command completed successfully in the same user account and Python environment used by the current shell. If you installed with pip's --user option, the executable is placed in a user-specific location that varies by system. Review the installer's output and ensure that the applicable user executable directory is available to the shell. Avoid inventing or copying a platform-specific path that does not match your Python distribution.

If both uv and pip installations exist, determine which executable the shell resolves and remove ambiguity before setup. Running setup with one installation and later invoking another can produce confusing version or configuration differences.

Setup finishes, but status is not ready

Run:

potpie status
potpie doctor

Review daemon, graph, backend, and skill results. Then confirm the active pot with potpie pot list. If the repository is absent, change into it and register it with potpie source add repo .. Repeat status after correcting the identified condition.

The harness does not appear to use Potpie

First prove that Potpie works without the harness by running a small potpie resolve or potpie search query. If the direct command succeeds, inspect which harness was chosen during setup and whether its Potpie skills are current. Use potpie skills install --agent <agent> only with an identifier confirmed by your installed version. For Claude, the documented identifier is claude. For Codex, use the setup wizard rather than guessing an identifier not established here.

The graph explorer does not open

Check potpie status and potpie doctor, then rerun potpie ui and read its complete output. The available evidence does not define a fixed URL that can be substituted manually. A failure to open the UI should be resolved at the Potpie layer before any Localtonet tunnel is created.

The local UI works, but Localtonet cannot reach it

Confirm that the Localtonet client runs on the same machine or on a machine that can reach the exact local service. Check that the selected authentication token belongs to that client, an available relay server is selected, and the tunnel is actually started. Compare the tunnel's local IP address and port with the endpoint discovered from potpie ui.

Do not change random ports until one works. That can accidentally expose an unrelated service. If the local endpoint uses a hostname, determine the corresponding address that the Localtonet client can reach rather than assuming a loopback or LAN address.

The public page loads but displays the wrong graph

A tunnel forwards to the configured service. It does not choose the active Potpie workspace. Use potpie pot list and potpie pot use <id-or-name> to verify the active pot, then confirm the repository source and reload the local UI before testing the public address again.

Integration verification fails

Compare potpie auth status with potpie auth status --verify. The first shows configured integration authentication state, while the second performs lightweight API verification. Reauthenticate only the affected integration and review the permissions granted to it. A working local daemon does not prove that an external source credential remains valid.

An older tutorial references service or manual ingestion commands

Potpie v2.0.1 removed unsupported legacy service and ingestion commands. Use the current setup, status, source, pot, resolve, search, graph, and UI workflows instead. The current documented model lets the configured agent ingest or update project context as needed, without a separate manual ingest command.

Frequently asked questions