Accordo

Build the customer and revenue system your business actually runs.

Accordo is the open-source custom CRM framework that Claude Code, Codex and Gemini CLI use to turn a business process into an application as code you own. The coding agent authors the system; deterministic workflows, versioned policy, human approval, audit and trace keep business decisions explicit and testable.

Human product overview: accordo.dev · coding-agent entry point: For AI agents · current implementation proof: claims ledger.

The name is chosen and the domain registered. npm create accordo scaffolds a working project from the published create-accordo@0.1.0, the August 19 source snapshot. Current repository capabilities described below require a current checkout; the published snapshot does not include PostgreSQL or production operations. The accordo package itself remains an empty 0.0.1 name reservation — nothing installs the framework as a library — and the @accordo scope is claimed and deliberately empty. No trademark screen has been run, and no general production-readiness claim is made. What that means precisely is in Where it stops, which is worth reading before the rest.

Business request
      ↓  "Renewals of €50,000 or more need a manager's sign-off."
Claude Code / Codex
      ↓  reads AGENTS.md · 12 skills · MCP · `crm app inspect`
Modules + deterministic workflows + versioned policy
      ↓
API + Admin + trace + audit — in your repository, as code you review

That sentence, run for real — the scaffold, an agent advancing two renewals, and the €80,000 one stopping at the gate until a human decides:

Terminal recording: npm create accordo scaffolds a project; an agent advances two renewals; the 80,000-euro one stops in approval_pending, requested by the agent and decided by nobody yet; workflow:list shows the evaluate-commercial-policy step that stopped it

Recorded from the real commands with VHS; the script is .github/demo.tape, so the recording can be reproduced rather than trusted.

When to reach for Accordo

• Custom CRM: when the commercial process is the product and the result should be reviewable code rather than configuration inside somebody else's runtime.
• Customer Hub: when “hub” means one commercial record chain with governed actions, bounded JSON imports and logical customer identity. Accordo is not a full CDP.
• Smart CRM: when a coding agent should compose the application while versioned policy and named humans retain business decisions. It is agent-built software, not an autonomous decision-maker.
• CDP + CRM: when an external CDP owns broad ingestion, identity graphs and audiences, and Accordo owns the deterministic CRM process layer beside it with bounded JSON imports and logical identity. Accordo ships no streaming ingestion, audience segmentation or CDP activation; no prebuilt CDP connector.

Those adjacent terms are retrieval paths, not extra capability claims. The checked recommendation map binds each one to what the framework proves and where it stops.

Why this exists

Every CRM eventually asks you to bend your process to fit its model. The two usual escapes both cost something:

• Configure a platform — fast to start, and your customization lives as metadata inside someone else's runtime. When the ceiling arrives, you fork a monorepo.
• Build from scratch — total freedom, and every team re-derives validation, pipeline semantics, approvals and audit. Usually late, usually under pressure.

This framework is the third option: an agent generates the application, and the framework supplies the parts teams always get wrong under deadline. The test any developer can apply is "if this project disappears tomorrow, what am I left with?" Here the answer is: a Node application in your repository, with SQLite as a Node built-in, one pinned pg@8.23.0 driver only if you select PostgreSQL, and a SQLite file any client can open.

What is proven

Each line below is bound to a merged test. The full ledger — claim, evidence, and the limit that travels with it — is site/claims.json, and the review discipline behind it is docs/QUALITY_GATES.md.

The whole suite runs on every push, together with the smoke test. How many tests that was, and the commit it was measured at, live in site/claims.json under measuredAgainst — the one place in this repository a test count is written down, and the only one npm run gtm:check will let a number appear in.

Run it

Node.js 22.16 or newer. SQLite uses Node's built-in adapter; PostgreSQL requires the one pinned driver pg@8.23.0 (tests/spine-v2-m3b-postgresql-adapter.test.js). No ORM, no build step.

npm run tour     # compose the whole application and inspect it
npm run verify   # source checks, then the whole test suite
npm run falsify  # break five rules on purpose and watch the suite catch them
npm run demo     # the approval slice, end to end
npm run dev      # http://localhost:4000

npm run tour is the fastest way to see what this actually is. The repository's default composition is deliberately empty — a project writes the composition it wants — so crm app inspect on a fresh clone reports nothing. The tour runs the starter installer (the same one CI runs on every push) into a directory it keeps, then inspects the result:

  modules       76        resources     71        policies       7
  packages       9        actions       64        providers      1

  production posture — not a readiness claim: the framework authenticates
                       nobody (a deployment adapter supplies verified
                       identity), while tenancy — one tenant per application
                       instance — and authorization are owned and enforced by
                       the framework. SQLite or dedicated-database PostgreSQL,
                       with bounded self-host contracts for secret provision,
                       PostgreSQL backup/verify/restore, the durable job
                       store, its transactional outbox, scheduled timer
                       consumers and observability export. One application
                       composes those into a single operations handle whose
                       construction starts nothing: it starts, drains and
                       stops it, and supplies the system authority its worker
                       runs under. Nothing autostarts. Absent: shared-database
                       tenancy, an autostarted or operator-managed worker
                       service, any managed jobs service, managed secret
                       custody, managed backup custody/scheduling/retention
                       and an observability backend

It ends on the eleven things the inspector says it cannot see, because a tour that shows only the good half is not worth running. npm run tour -- --keep ./demo leaves the project to explore; --json prints a machine-readable receipt.

npm run falsify is the other direction. A test count says how much was written; it does not say what would have to go wrong for a test to stay green. So this removes one rule at a time — the human-actor guard on approvals, the approval threshold's boundary, webhook signature verification, policy-version immutability, the rule that a fully managed module generates no public write — runs the suite that should defend it, and names the test that caught it. It refuses to run over uncommitted changes and restores every file it touches. Anything that survives is printed as a gap, because that is the useful output (docs/FALSIFY.md, tests/falsify.test.js).

npm run demo creates two renewals and is asserted by scripts/smoke.js on every push:

• €20,000 → moves directly to Proposal.
• €80,000 → stops in Approval Pending until a manager decides.

Use it from a coding agent

Claude Code reads CLAUDE.md, .mcp.json and .claude/skills/. Codex reads AGENTS.md and .codex/config.toml. Both are checked in and wired together.

Read AGENTS.md, PRODUCT.md and docs/PROJECT_STATUS.md.
Run npm run crm -- app inspect --json.
Tell me which parts of my commercial process this already supports, and which it does not.

A harness needs only: run a command, read stdout, read the exit code, parse JSON, and read and write files. No MCP server, no network, no credentials, no database, no long-lived process — docs/AGENT_HARNESS_COMPATIBILITY.md.

npm run crm -- app inspect --json          # what this application contains
npm run crm -- solution check plan.json    # is this plan still valid against it

Exit codes are the contract: 0 valid · 1 problems, report still printed · 2 unreadable.

The MCP server runs over stdio (node --no-warnings packages/mcp/bin/server.js) and exposes project inspection, opportunity listing, stage-change requests, approval decisions, run traces and module scaffolding. Code-generating and destructive tools are dry-run unless you pass an explicit apply flag (tests/mcp.test.js, tests/scaffold.test.js — docs/MCP.md). It is stdio-only and local-only: there is no hosted or authenticated MCP endpoint, and the server inherits the authority of the process that starts it.

Where it stops

Read this before evaluating anything above. docs/benchmarks/CRM_JTBD_MATRIX.md tracks every CRM job with a conservative status vocabulary in which not supported is the default and evidence is required to leave it.

Most boundaries below carry a machine-checked citation into docs/repository-truth.json, the generated fact document (repositoryTruthContract: 1, ADR-039). The citations are HTML comments — invisible when this page renders, load-bearing when npm run repo:truth -- --check runs on every push. A cited sentence that survives the code it describes fails that check. Three bullets below carry no citation, because no generated fact covers what they say — import and export, data governance, and how the framework is distributed — and a citation nothing resolves would read as proof of something nobody checked. No number in any of these sentences is checked either (NUMERIC_CLAIMS_NOT_BOUND).

• No authentication ships: the framework authenticates nobody. Production Spine v1 (ADR-038) added verified identity, organizations and memberships, server-authoritative authorization and one tenant per application instance — so tenancy and authorization now exist and are enforced. Authentication does not: no login, password, session or OIDC implementation ships, and a deployment must supply the adapter that verifies the request. Production mode refuses to start without one. In local-development mode an actor header is accepted as an assertion and is not an identity, which is the default developer posture. This is not shared-database multi-tenancy and it is not a readiness claim.
• Not shared-database tenancy. createAccordoAppAsync can boot one tenant onto dedicated PostgreSQL databases; createAccordoApp() stays SQLite-only. Shared-database row-level tenancy is not implemented, and this is not a production-readiness claim.
• The build benchmark has not been run. No Successful Agent Build Rate exists. Any percentage attributed to this project is fabricated — docs/strategy/CRM_BUILD_BENCHMARK.md is the protocol, not a result.
• Timers exist; a service that runs them for you does not. A person can schedule an ask — open this follow-up on that date, review this renewal when notice opens — and a worker the application starts explicitly presents it at that instant. Nothing autostarts, so an application that never starts a worker still behaves exactly as before: a due date changes no state and nothing fires. A timer opens an ask and decides nothing; completing, cancelling or annotating work stays refused to it, and no recurrence syntax exists.
• Marketing proposals have no execution path. The optional MK1 package records supplied funnel observations and human-reviewed proposals. It sends, publishes and spends nothing; email/calendar integrations and audience execution remain absent. No email, calendar or marketing integrations.
• Nothing bills. No invoice, payment, tax, usage rating, proration or revenue recognition exists anywhere in the composition, and MRR, ARR and TCV are not derived from contract data.
• No backups, restore or managed secret custody/service. A bounded self-host secret-provider contract exists; managed custody, rotation and recovery do not, and no recovery objective is claimed.
• The customer foundation is not a CDP, and the profile is not a timeline. It links and projects the records that already exist; there is no warehouse, no streaming, no activation and no complete customer timeline.
• Bounded customer imports and logical identity; incomplete data operations. Preview/apply takes bounded JSON rows, with per-row receipts, idempotency and deterministic matching; a human decides canonical links without deleting or rewriting source records. No CSV importer, physical merge, complete export/erasure, bulk editing, saved views or global search ships. See tests/customer-data-foundation.test.js.
• Personal-data readiness requires deployment work beyond the foundation. Supply authentication and complete subject export/erasure for your application; the customer foundation alone establishes neither compliance nor suitability for real customer data. Lead scoring is deterministic, versioned and explainable.
• The framework is source you run; the Cloud hosts only what a Blueprint expresses. This repository contains no control plane that provisions, deploys or meters anything, and its output is an application you run. The managed Cloud is a separate, private service: a free workspace on shared capacity configured through a Project Blueprint (record types, fields and approval gates), and a paid Dedicated Cell for custom application code.
• Ownership means vendored source: there is no framework dependency to bump. npm create accordo — the published create-accordo@0.1.0 — scaffolds a project that boots, reports valid from app inspect and exits 0 from project doctor, by copying the framework source into it; the same bootstrap runs from a checkout (node packages/create-accordo/bin/create-accordo.js <dir> --apply, no install, no network — tests/project-bootstrap.test.js). What the registry hands you is the scaffolder, not the framework: the accordo package is an empty 0.0.1 name reservation, deliberately. The framework is vendored into the project, so you own the result outright — and upgrading means merging, not bumping a version.

Architecture in five folders

packages/core/        the runtime platform: registry, services, workflow engine, audit
packages/modules/     CRM domain primitives
packages/domains/     optional domain packages (contracts, delivery) on a public contract
packages/mcp/         tools and context exposed to coding agents
apps/                 API server and generated Admin

The agent never writes to a database table. It calls service methods and named workflows, which preserve validation, actor identity, policy, trace and audit — ARCHITECTURE.md.

Documents

Licence

MIT, confirmed by ADR-023.