An operating system for go-to-market that you host and agents run.

Who it is for

The core idea

GTM OS is built so that an AI agent can do the work of a GTM engineer without being trusted blindly. The agent gets the same operations a human admin has. What it cannot do is approve its own work, widen its own authority, consent to OAuth in a browser, or switch off the safety switch. Those stay with people. In plain terms: the agent builds and proposes, a second human decides, and the kernel records who did what.

The README compares it to WordPress: a stable core you install on your own infrastructure, plus packages that deliver the work. You own the data and the deployment, and you can take your data out at any time with gtm org export.

How it is delivered

npm i -g @gtmos/cli
mkdir my-gtm && cd my-gtm && claude
! gtm init                      # agent workspace + docs, even with no instance yet
/setup-gtmos                    # Claude runs gtm setup, the agent key, connections

# by hand instead:
gtm setup ./instance --org Acme --email you@x.com --approver-email ops@x.com --version 0.2.5
gtm doctor --strict             # what is live, unverified, missing

Self-hosting and upgrading

02 · Architecture

Kernel, stdlib, apps, SDK, packages

The repo has four layers. The kernel is the stable core; stdlib is the first-party GTM content built on it; apps are the processes you run; the SDK is the public API that packages build against.

flowchart TB
  subgraph People["Humans and agents"]
    H["Console users"]
    AG["Claude Code, Codex, any MCP agent"]
    OP["Operator with the gtm CLI"]
  end
  subgraph Apps["apps"]
    CON["console (Next.js)"]
    API["api (REST, tRPC, OpenAPI)"]
    MCP["mcp (streamable HTTP)"]
    WK["worker (jobs, plays, agent loops)"]
  end
  subgraph Kernel["kernel"]
    REG["Operation registry and pipeline"]
    POL["Policy: Cedar, gate, Dry Mode"]
    DP["Data plane: observe, resolve, project"]
    BR["Broker and cost ledger"]
    MG["Model gateway"]
    FL["Flow runtime, plays, lanes"]
    CFG["Config store, environments"]
  end
  subgraph Stdlib["stdlib packages"]
    ENG["Engines"]
    ONT["Ontology modules"]
    CNX["Connectors"]
    SCR["Screens and packs"]
  end
  DB[("Postgres with RLS and pgvector")]
  H --> CON
  AG --> MCP
  OP --> API
  CON --> API
  API --> REG
  MCP --> REG
  WK --> REG
  REG --> POL
  REG --> DP
  REG --> BR
  REG --> MG
  REG --> FL
  REG --> CFG
  ENG --> REG
  CNX --> BR
  DP --> DB
  CFG --> DB
  

The kernel

The kernel lives in kernel/*. It imports nothing from stdlib, and packages never get a raw database connection: the only database access goes through kernel stores under row-level security. CI enforces these boundaries with dependency-cruiser.

stdlib, apps and the SDK

Packages and execution tiers

Package lifecycle operations: packages.install, packages.enable and packages.disable (per environment), packages.upgrade, packages.rollback, packages.uninstall, with packages.preview_upgrade as a read-only diff. The CLI mirrors them under gtm pkg, plus offline tooling to scaffold, validate, build (hash and SBOM) and sign.

The operation pipeline: an agent asks, a human decides

This is the path every call takes, whether it comes from the console, the CLI or an agent over MCP. A read runs straight through. A customer-facing effect stops at the gate and waits.

sequenceDiagram
  participant A as Agent
  participant M as MCP server
  participant K as runOperation
  participant G as Approval gate
  participant H as Second human
  A->>M: gtm_describe outreach.send_message
  A->>M: gtm_act outreach.send_message
  M->>K: validate, org context, authz, guards
  K->>G: disposition is require approval
  G-->>A: approval id, state proposed
  H->>G: runtime.approve_action
  H->>G: runtime.execute_approval
  G->>K: execute
  K->>K: outbox event and hash-chained audit row
  

The pipeline stages, in order: validate the input against the operation's schema, resolve the org context, authorize (Cedar plus scope checks), run guards and transforms, compute the disposition (gate policy, Dry Mode, autonomy caps, lane controls, binding mode), create an approval if one is needed, execute, then write the outbox event and the audit record in the same org transaction.

03 · Core concepts

The ideas you need before anything else

Operations and their classes

Definitions

Lifecycle: draft, propose, sign, promote

A definition cannot be published straight into prod. It is drafted in dev through a ChangeSet, proposed for signing, signed by a human who did not propose it, then promoted. Engines read only the signed version in the call's environment; with none, they fall back to their stdlib default. Editing a definition creates a new version that must be signed again. definition.data_monitor is the one sign-exempt kind.

config.propose_changeset      -> draft ChangeSet         (gtm plan / gtm apply --env dev)
config.validate_changeset     -> issues, nothing applied
config.apply                  -> approval; a different human approves -> published in dev
definition.propose_for_signing-> proposed                (gtm definition propose-for-signing)
definition.sign_many          -> signed, by a human, not the proposer   (gtm definition sign-all)
env.promote dev -> prod       -> ONE approval            (gtm promote --all dev prod)

Environments

Approvals and four-eyes

Dry Mode

Two layers of safety switch, both human only to change. The organization-wide switch (Settings > Safety, policy.set_dry_mode): while it is on, every E-class operation becomes a draft, logged, never executed, no approval created. D, T and M operations still run. Every console page shows a banner. Read it with policy.get_dry_mode. Each engine also has its own Dry or Live mode (policy.engine_modes.get and policy.engine_modes.set; Settings > Safety and the header of each engine page), covering outreach and sequences, meeting booking, performance ads, SEO & GEO publishing, lifecycle plays, routing notifications, CRM write-back, enrichment spend and merges. The effective mode is the stricter of the two. Going live is an owner or admin action, confirmed and audited, and policy.shadow_report shows each engine's accuracy from its dry runs.

Guardrails are enforced by the kernel for every engine and agent: emails a day, new accounts contacted a week, ad spend a day (above it a person approves), a send window in the recipient's timezone with quiet hours, and allowed channels (policy.guardrails.set). A hit holds the action instead of dropping it, raises an alert and runs it later. One rule has no setting: the first message to someone nobody has written to is never sent automatically.

Proof library and the claims gate

Budgets and spend caps

Spend is visible in Operate > Cost (ledger.list). Price before running with capability.quote or enrichment.enrich_accounts {estimate: true}.

Provenance and lineage

Every value on a record knows where it came from: the winning observation, the others that competed, the survivorship rule, a confidence from 0 to 1, a band (VERIFIED, PROBABLE, POSSIBLE) and a status. A human edit is VERIFIED and automation never overwrites it. Read it with records.provenance and lineage.trace (MCP gtm_lineage_trace); the CRM record pages show a provenance panel.

Readiness and required connections

instance.readiness (CLI gtm doctor) lists every seam with a status: live, configured_unverified, failed, fixture or not_configured. Items are required while the engine that needs them is in use, otherwise informational. Applying a blueprint makes its declared connections required. The console shows the same list as Required connections on Integrations > Connections.

04 · Ontology and data

One model of your market

Canon objects you will use most

Optional ontology modules add more when enabled: stdlib/gtm.partner (partners, tiers, partner deals, referrals, commissions), gtm.search (properties, pages, keywords, SERP positions), gtm.ads, gtm.b2c, gtm.company (products, price books, territories, quotas). Check packages.catalog before inventing an object a module already provides.

Custom fields and custom objects at runtime

Identity resolution

Two layers keep one record per real company and person.

1. Observation to entity (data plane). An account matches on domain (authoritative) and name (corroborating); a contact on primaryEmail and displayName. Matching runs deterministic, then blocking, then probabilistic; unsafe matches go to a human review (resolve.review.decide). A signed definition.identity_rule overrides the keys and survivorship (most_recent, highest_confidence, first_write_wins, longest_non_empty, source_priority).
2. Record dedupe (the Merges engine). identity_dq.scan_duplicates follows the signed definition.identity_rule, then identity_dq.merge_records as an approval that lists each field conflict and the strategy that decides it, reversible with identity_dq.unmerge_records. A merge keeps survivor columns a person set by hand.

Automated writes onto an existing record must resolve to that record by domain, email or source id. A write that cannot resolve never creates a duplicate; source mappings report it as unresolved.

Mirror (binding) modes

Set per object type with binding.set_mode or gtm connect <provider> --mode <mode>. CRM sync and source mappings respect it.

Vectors and search

search_records (MCP) fuses Postgres full-text rank with pgvector similarity over accounts, contacts, deals and activities. Embeddings come from OpenAI (text-embedding-3-small) or Gemini (gemini-embedding-001), whichever key the org has. Anthropic has no embedding model; without OpenAI or Gemini, results come back mode: "text_only". Indexing runs as a daily background sweep; search.index_status shows coverage and search.reindex_now runs it on demand.

The CRM

05 · The engines

What does the work

For engineers: how the engines work together and a page per engine with prompts and verification.

The console lists eight engines: Score, Outreach, Performance Ads, SEO & GEO, Enrichment, Merges, Plays and Routing. Every engine page opens on an overview with its mode (Dry or Live), KPIs, what it needs, approvals waiting, recent actions with undo, the definitions it uses and its plays. Around them sit signals, the research agent, CRM sync, source mappings, the search index and agent chat. Every engine runs on your signed definitions in the call's environment and falls back to a stdlib default. Build in this order: data first, then scoring, then routing and plays, then the outbound channels.

06 · End-to-end flows

How the pieces move together

From signal to approved send

This is the default path with both workflow flags on (signals.reaction, qualification.handoff). No custom play is needed.

flowchart TD
  S["Signal recorded: funding, hiring, visit, form"] --> R["signals.reaction re-scores the account"]
  R --> Q{"Qualified by your scoring model?"}
  Q -- "no" --> W["Stays warm, watched by scans"]
  Q -- "yes" --> HO["qualification.handoff"]
  HO --> O["Owner assigned, round-robin or your list"]
  HO --> T["Follow-up task due in 2 days"]
  HO --> E["Contact enrolled in the lane-bound sequence"]
  E --> D["Message drafted in your brand voice"]
  D --> P["outreach.send_message proposed"]
  P --> C{"Pre-send checks pass, claims backed by proof?"}
  C -- "no" --> X["Blocked: suppression, cap, open deal, unbacked claim"]
  C -- "yes" --> A["Second human approves and executes"]
  A --> M["Sent from the lane mailbox, logged"]
  

Connect an app with Composio and sync it into the ontology

flowchart LR
  A["Connect Composio: sign-in, ck_ or ak_ key"] --> B["composio.connect an app, human consent"]
  A --> SC["composio.sync_connections finds apps already connected"]
  SC --> C
  B --> C{"Is it your CRM?"}
  C -- "yes" --> D["crm.settings.set, then crm.sync every 6 hours"]
  C -- "no" --> E["source.preview and source.suggest_mapping"]
  E --> F["definition.source_mapping, signed by a human"]
  F --> G["source.sync on its schedule"]
  D --> H["gtm.account, gtm.contact, gtm.deal, gtm.signal"]
  G --> H
  H --> I["Identity resolution and dedupe review"]
  

Build and go live

flowchart LR
  A["Discovery interview"] --> B["blueprint.apply into dev"]
  B --> C["Customize definitions in dev"]
  C --> D["config.apply approved by a second human"]
  D --> E["definition.propose_for_signing"]
  E --> F["definition.sign_many by a human, not the proposer"]
  F --> G["env.promote dev to prod, one approval"]
  G --> H["lane.activate, SPF DKIM DMARC checked"]
  H --> I["go-live-check returns GO"]
  

In the console, Environments > Go live does the sign and promote in two clicks: "Review & sign all proposed (N)", then "Promote dev → prod". The /go-live-check command runs a read-only GO / NO-GO list: live mode, gtm doctor --strict, readiness, the Search Console requirement (if SEO is used), engines enabled, definitions signed in the target environment, a live check per engine, a second approver, Dry Mode off, and caps.

07 · Integrations

What GTM OS connects to, and why

looot: third-party data

Composio: your own apps and actions

Per-org MCP servers

Any streamable-HTTP MCP server can become a capability backend for one org, without a restart. mcp_servers.add stores the URL and auth header sealed, mcp_servers.test runs a live initialize and tools/list, and a human marks each tool read or write with mcp_servers.set_tool_effects. Bind it with definition.binding {backend: "mcp", opId: "mcp:<server>:<tool>"}. An undeclared tool is unusable; a write tool needs riskClass: "high_risk", broker.accept_high_risk and a second human's approval on every call.

Native connections

Mail and calendar sync every 10 minutes and auto-log activities with known contacts.

The Connections page

Integrations > Connections is a searchable grid of brand-logo tiles in 11 categories. Each tile shows whether it connects Native or Via Composio, with a choice where both exist, and a Needed strip lists what your chosen blueprint and engines still need. Press / to jump to the search box. Sort by relevance to your setup (the default), A to Z or connected first. Statuses are honest (live, stored but not verified, failed, not connected), and in demo mode a tile says it uses built-in sample responses, not your data. Instance keys are shared with an organization only for the providers in GTMOS_PLATFORM_CREDENTIAL_PROVIDERS. No native card exists yet for Instantly, lemlist, Smartlead, Gong, Mixpanel or Amplitude: use Composio.

Model providers

At least one of Anthropic, OpenAI, Gemini or OpenRouter (one key for many vendors, generate-only) must be live, as an org Connection or an instance key. Default models: claude-sonnet-5-5, gpt-4o, gemini-3.8-flash, overridable per provider with GTMOS_DEFAULT_MODEL_<PROVIDER>. Pin routes per task class (reasoning, drafting, classification, extraction, embedding) with definition.model_policy. Region-specific routing fails closed without a configured regional endpoint.

08 · Flexibility and customization

Change almost anything, through an agent, under review

For engineers: the GTM engineer guide has copy-paste prompt recipes for every kind of change, and governance explains who approves what.

GTM OS is designed so that you, through Claude Code, Codex or any MCP agent, can reshape the system to fit your motion. Engines, data model, data sources, integrations, starting templates, packages and screens are all configuration. The agent writes it; your team signs it; it goes live.

What you can customize

Agent parity

An agent key with the Full GTM engineer preset (the Claude Code default), acting for an owner or admin, can do everything that person can do in the console through operations: records, fields, pipelines, definitions (proposed), research settings, CRM settings, workflow flags, connections and keys the user hands over, MCP servers, syncs, scans. Four things stay human and return FORBIDDEN:

Effective authority is the intersection of the key's scopes, the agent's scopes and the creating human's current role, re-checked on every call. Demote the human and the key shrinks. action.approve can never be granted to a key. Kill an agent everywhere with agent.kill.

The harness: gtm init

The agent's tools over MCP: gtm_describe (always first), gtm_query, gtm_get, gtm_search, gtm_act, gtm_approvals, gtm_lineage, gtm_lineage_trace, search_records.

The ten blueprints

General templates, applied with blueprint.apply or gtm apply --from <id>. Each seeds a whole motion in one change set and makes its declared connections required. Every one except seo needs a model provider, looot and (where it sends) an email sender.

gtm blueprint list and gtm blueprint show <id> browse the catalog offline, gtm blueprint upstream --org <id> shows which blueprint an organization derives from, and gtm blueprint upgrade produces a reviewable diff and, with --yes, proposes it for approval. The user guide lists what each one sets up.

Customizable now, or needs a new release

09 · Security and governance

Who can see, do and approve what

Roles

Controls at a glance

10 · Glossary

Terms, GTM and technical

11 · What is not built yet

Honest limits in 0.2.5

These come from the release notes and the shipped guides. Plan around them rather than discovering them during a pilot.

Integration maturity

Needs a live check with real accounts

The code is tested against contracts and a live database, but these need a real account. Treat them as unverified until you have checked them.