Set up PipeLedger for AI agents

Start in the chat app you already use. Move to an agent on your own computer when you want it to know your business before you ask. System agents are for work that should run without you.

A chat app connects through a custom connector to https://mcp.pipeledger.ai/mcp. There are two routes, and an Owner or Admin chooses by who the person is.

Both routes apply the same access rules and leave the same audit record. The difference is what a person can see beyond their own answers. A member can open the PipeLedger application. A person with an access credential sees only answers about their slice.

Issue one access credential for each person. Disabling it ends every connection made with it. The steps and the token lifecycle are in the OAuth connection guide.

A working folder gives your agent a consistent reference for how your organization reports and reviews its finances. Keep your instructions, approved policies, and recurring procedures together so the agent can consult them during its work.

Start small: describe the business, explain what you need from reporting, and add one procedure you want help with. Expand the folder as you identify useful guidance.

What useful guidance looks like

You do not need a separate document for every topic. Use existing documents where they are current, and add short notes where important knowledge is still held by individuals.

Install the pl command

npm install -g @pipeledger/cli
pl --version

The command needs Node.js 20 or later. The commands on this page need version 0.1.2 or later of pl.

Create the workspace

pl login
pl init

pl login asks for the service credential with a hidden prompt and saves it outside the folder. An Owner or Admin creates that credential in PipeLedger and chooses its role, tools, data, and clearance. pl init then creates the workspace, links it to that credential's organization, and prints the folder it created. It contacts no server.

Documents/PipeLedger/
  methods/                  your own methods, no organization data
    procedures/             for example month-end-review.md
    templates/              for example review-memo.md
  clients/
    your-organization/
      AGENTS.md             starter instructions your agent reads first
      CLAUDE.md             points Claude to AGENTS.md
      reference/            reporting strategy, policies, contracts
      notes/                decisions and open questions
      reports/              draft analyses and reviewed reports
      .pipeledger.json      connection selected for this folder

• Where it goes. Documents/PipeLedger in your home folder, or PipeLedger in your home folder when there is no Documents folder. Choose another place once with pl init <name> --root <path>; it is remembered.
• The folder name. The profile name, which pl login takes from the organization. Use --folder to choose another.
• Nothing is replaced. Each file is written once. Running pl init again restores what is missing and leaves your edits alone.
• Already have a folder? Run pl link <name> in it. That connects the folder to the books and creates no files.

Codex reads AGENTS.md and Claude Code reads CLAUDE.md, which points to the same instructions, so they are written in one place. Keep your existing document formats where practical.

The files guide the agent's work. Editing them does not change account mappings, metric definitions, or access permissions in PipeLedger.

Make it yours

1. Install the agent and open it on the organization's folder, the one pl init printed.
2. Confirm the connection. In that folder, pl whoami should name your organization and show that the profile was chosen by the folder.
3. Complete the instructions. AGENTS.md has two sections for you to write, "The client" and "How I want work done". The starter below is enough for the second.
4. Add the guidance your finance team works from: your reporting strategy, chart-of-accounts structure, accounting policies, rules for keeping accounts and activities separate, intercompany policies, and review procedures. Start with the documents you already use and add context as questions arise.

Each saved credential is a profile: one organization, one name. pl init gives each organization its own folder, linked to its own credential.

Each organization's folder selects its saved PipeLedger connection unless you explicitly override it. Open the agent in that folder and confirm the organization with pl whoami. File access is controlled by your agent's workspace permissions; the PipeLedger folder link does not restrict which local files it can read.

Set up two organizations

Replace the profile names with your own. Each pl login asks for that organization's service credential.

pl login --profile organization-a
pl init organization-a

pl login --profile organization-b
pl init organization-b

pl switch

pl switch lists both organizations with their folders. In each folder, pl whoami should name that organization and show that the profile was chosen by the folder.

YOURS: read for every organization, holds none of their data
Documents/PipeLedger/methods/
  procedures/
  templates/

ORGANIZATIONS: one folder each
Documents/PipeLedger/clients/
  organization-a/
    AGENTS.md  CLAUDE.md
    reference/  notes/  reports/
    .pipeledger.json   connection for organization A
  organization-b/
    AGENTS.md  CLAUDE.md
    reference/  notes/  reports/
    .pipeledger.json   connection for organization B

CREDENTIALS: private to you
~/.pipeledger/profiles/

pl init names the parent folder clients. If you prefer your own layout or names, create the folders yourself and run pl link <name> in each.

• One session, one organization. Start the agent inside the organization's folder. For another organization, start another session.
• Open one organization's folder, not the folder above it. An agent opened on clients could read every organization's material in one session.
• Methods are shared. Information is not. Your procedures and templates in methods serve every organization and hold none of their data. Nothing is copied from one organization to another.
• Side by side, never one inside another. A command uses the nearest folder link, so pl init does not create a workspace inside a linked folder.
• Link folders for parallel work. Two agents in two linked folders can work on two organizations at the same time. A default that is switched back and forth is shared by every terminal, so it cannot do that.

What the folder link does and does not do

• It selects a connection. .pipeledger.json names the profile and the organization. --profile on a command, or PIPELEDGER_PROFILE, overrides it for that command.
• It holds no credential. The folder can be synced or shared. A colleague who receives it must save their own credential for the same organization under the same profile name before the link works on their computer.
• It does not limit file access. Your agent's workspace permissions decide which local files it can open, including another organization's folder.
• It is not authorization. PipeLedger enforces the credential's permissions on every request, whatever the folder says.

Several legal entities can share one connection and one folder when the credential's permissions cover them.

A chat question such as "What was revenue?" leaves the organization, the period, and the comparison open. An agent in a workspace can take a brief instead: a piece of work with a defined result, done from your procedures, your documents, and the books.

• Name the result. A review, a reconciliation, a draft memo, a list of exceptions.
• Name the scope. The period, the entities, and the procedure to follow.
• Join the folder and the books. The strongest briefs check something only you hold, such as a lease, a loan schedule, or a decision in your notes, against what was recorded.
• Ask for the evidence. PipeLedger returns the ledger lines behind a figure, so every finding can be checked.

PipeLedger supplies the published figures and their supporting lines. The agent compares them with your documents and drafts the result. You review it, decide, and act. PipeLedger does not post journals, send messages, or initiate payments.

The profiles folder is the only place pl looks for saved profiles. A credential never belongs in an organization's folder, a chat message, an email, a screenshot, a typed command, or an agent's instructions.

How a profile is chosen

1. --profile <name> on the command, or PIPELEDGER_PROFILE.
2. The folder link: the nearest .pipeledger.json in the current folder or a folder above it.
3. The default chosen with pl switch <name>.
4. The only saved profile, when exactly one is saved.

When nothing selects a profile, or the selection is missing or unreadable, the command returns a connection error. It never falls through to another organization. Before a financial request, pl also confirms with PipeLedger that the credential belongs to the organization the profile names.

The two automation settings are alternatives to a profile. Combining one with a profile or a linked folder is a conflict, and the command returns a connection error.

These are different acts. pl logout removes a credential from one computer. The credential still works anywhere else it was saved. Revoking it in PipeLedger ends it everywhere, and the next request is refused.

Sign out when you stop working for an organization or change computer. Ask an Owner or Admin to revoke when a credential may have been exposed or a person leaves. After signing out, pl does not choose another organization for you.

These rules apply when you act for a person who uses PipeLedger.

1. Run pl whoami before any other request, and state the organization you are working in.
2. Never ask a person to paste a credential into a conversation, and never write one into a file, a command, or your instructions. Ask them to run pl login themselves.
3. Do not open, copy, or move files in ~/.pipeledger/.
4. When a command returns a connection error, report the message. Do not work around it by setting an environment variable, naming another profile, or changing folder.
5. Work on one organization in one session. The folder link does not stop you opening another organization's files, so do not open them, and do not carry figures, notes, or files from one organization's folder into another's.
6. If pl whoami reports a partial ledger, never present a result as the organization's complete ledger.
7. Return the evidence with the answer. The person reviews it, decides, and acts. PipeLedger does not post journals, send messages, or initiate payments.

If PipeLedger cannot safely select or authenticate a connection, the command returns an error instead of running the requested operation.

When you contact support, include the error code and any correlation ID shown. See the PipeLedger Tool Guide for what each command returns, and the support page for help.