Module structure
Bide is a multi-module repository: a dependency-light core module plus one module per heavy adapter. This keeps a consumer's dependency/audit surface proportional to what they actually import.
Why
The core module requires nothing outside the standard library (TestCoreModuleRequiresNothing holds its go.mod to no requirement). The adapters, however, pull large dependency trees: modernc pure-Go SQLite alone is 34 modules. As a single module, a consumer who imported only the core still inherited the whole set in their go.sum / go mod graph / SCA audit surface (Go's module-graph pruning keeps them from compiling unused adapters, but they still appear to dependency scanners).
Measured before the split: a core-only consumer inherited 54 external modules; they now inherit none. gsm is not among them: it belongs to the govern module. Each heavy tree lives behind its own module and is pulled in only when that adapter is imported.
The modules
| Module | Path | Extra deps beyond core |
|---|---|---|
| core | github.com/bide-ai/bide | none (standard library only) |
| govern | …/govern | blackwell-systems/gsm |
| mcptools | …/mcptools | modelcontextprotocol/go-sdk (+ jsonschema, segmentio, …) |
| trace | …/trace | go.opentelemetry.io/otel |
| sqlite store | …/store/sqlite | modernc.org/sqlite |
| postgres store | …/store/postgres | jackc/pgx |
| redis log | …/govern/redislog | redis/go-redis |
| sqlite log | …/govern/sqlitelog | modernc.org/sqlite |
| postgres log | …/govern/postgreslog | jackc/pgx |
| PKCS#11 signer | …/signer/pkcs11 | miekg/pkcs11 (needs cgo; without it the module builds and Open returns ErrNoCgo) |
| AWS KMS signer | …/signer/awskms | the AWS SDK for Go v2 KMS client |
| Azure Key Vault signer | …/signer/azurekv | the Azure SDK for Go (azcore, azidentity, azkeys); ECDSA P-256 only |
| Google Cloud KMS signer | …/signer/gcpkms | cloud.google.com/go/kms |
| S3 Object Lock anchor | …/anchor/awss3 | the AWS SDK for Go v2 S3 client (and its bide-anchor command) |
| Google Cloud Storage anchor | …/anchor/gcs | cloud.google.com/go/storage (a locked bucket retention policy; its heads are read by bide-anchor -backend gcs) |
| gcf codec | …/codec/gcf | blackwell-systems/gcf-go |
| flow editor | …/flowedit | go.yaml.in/yaml/v3 (it splices a flow config's YAML text, which the core module, with no dependency, cannot) |
| bide command | …/cmd/bide | the two store modules, flowedit, go.yaml.in/yaml/v3 (a program, installed with go install, not imported) |
| bide-hsm command | …/cmd/bide/bide-hsm | the PKCS#11, AWS KMS, Google Cloud KMS and Azure Key Vault signers (signer/pkcs11 needs cgo), the AWS SDK, the Cloud KMS client, the two store modules, and cmd/bide for its internal approval code (a program, built from source with go install; not in the release archives) |
| bide-anchor command | …/cmd/bide-anchor | the AWS SDK for Go v2 (through anchor/awss3) and the Cloud Storage client (through anchor/gcs); a program, installed with go install, with -backend choosing the object store |
The core module keeps everything with no heavy deps: agent (loop), approvals (the HTTP intake for signed approval decisions, and the browser approve page), schema, middleware, model/anthropic, model/openai, model/gemini, plan, audit, eval, chaos, cmd/bench, the code of bide view and bide audit (internal/runview, internal/auditcli), and most of examples. The bide command (cmd/bide) is its own module because bide view and bide demo need the store drivers; built with -tags bide_audit_only it links nothing outside the core module. The architecture_test.go guards are allowlists: the agent and plan packages' import graphs hold only the standard library and the core module's own packages (and not its model adapters or middleware), and TestCoreModuleRequiresNothing holds the core module's go.mod to no requirement and its go.sum to empty, so gsm, or any other module, cannot enter the core unnoticed.
govern is its own module so the core does not depend on gsm. It stays v0.x until gsm is stable, while the core moves on its own schedule. It uses only the core's exported API (never a package under internal/), which its TestGovernImportsNoCoreInternal enforces. The three governed-event log modules (govern/redislog, govern/sqlitelog, govern/postgreslog) require it.
More modules are not libraries you import; they exist so their dependencies stay out of the core:
| Module | Path | Why it is separate |
|---|---|---|
| approval example | …/examples/approval | imports store/sqlite |
| plan example | …/examples/plan | imports store/sqlite |
| mcp example | …/examples/mcp | imports mcptools and the MCP go-sdk |
| observability example | …/examples/observability | imports trace and the OpenTelemetry SDK |
| governance examples | …/examples/govern | nine programs (authority, compliance, compose, coordination, delegation, earned-authority, mesh, proof-carrying-run, quorum) that import govern and gsm |
| HSM signing example | …/examples/hsm-signing | imports the signer modules (PKCS#11, Google Cloud KMS, Azure Key Vault) |
| SSO certificates example | …/examples/sso-certs | a step-ca recipe with an end-to-end test against containers |
| Stripe refund example | …/examples/stripe-refund | drives Stripe's test-mode API |
| emulator and fake-server tests | …/signer/awskms/emulatortest, …/signer/gcpkms/emulatortest, …/cmd/bide/bide-hsm/emulatortest, …/cmd/bide/bide-hsm/azuretest | test-only: run the KMS signers and bide-hsm against in-process emulators, keeping them out of the signers' module graphs |
| integration tests | …/integration | test-only: the core's tests that need govern and gsm (the many-agent convergence test, the run-certificate tests over real gsm policies, and the bide audit CLI tests fed by quorum runs and convergence certificates) |
| benchmarks | …/benchmarks | the cross-SDK chaos comparison: eino, langchaingo, adk-go, trpc-agent-go |
The example and integration modules are in go.work; benchmarks is not, so run it with GOWORK=off from its directory.
Working in the repo
A root go.work ties the modules together for local development, so go build/tests resolve cross-module references without published versions:
go work sync
cd trace && go test ./... # or any moduleOn main, each nested module's go.mod requires the core (and govern, for the log backends) at the placeholder v0.0.0 and carries a replace github.com/bide-ai/bide => <rel>, so it builds standalone against the code in the tree, with or without the workspace (GOWORK=off). CI builds and tests every module in its own directory (see .github/workflows/ci.yml, MODULES), except benchmarks, which CI does not run. The Lint job fails if a module in the tree is missing from MODULES or from go.work, and the Changes job if a module in MODULES is not in exactly one of the Linux test shards (TEST_SHARDS); the core is split there, its agent package in a shard of its own (.:agent) and the rest of its packages in another, and Lint fails unless each of the core's packages is in exactly one.
Releases
The core and the library modules are released together, with one version. scripts/release.sh tags the core vX.Y.Z on main, then makes a commit, reachable only from the release tags, that sets each library module's require on the core (and on govern, for the log backends) to vX.Y.Z, drops the replace directives, and records a go.sum resolved through the module proxy. It tags each library module <dir>/vX.Y.Z at that commit, so a consumer's go get resolves every module from the proxy. Main keeps its replace directives, so development is unchanged.
Published (tagged at every release): govern, store/sqlite, store/postgres, mcptools, trace, codec/gcf, anchor/awss3, anchor/gcs, flowedit, govern/sqlitelog, govern/redislog, govern/postgreslog, signer/pkcs11, signer/awskms, signer/azurekv, signer/gcpkms, and the commands cmd/bide, cmd/bide/bide-hsm and cmd/bide-anchor. cmd/bide-view, a stub that only pointed to bide view, was tagged with every release through v0.25.0 and is removed: its last tag is cmd/bide-view/v0.25.0, where go install github.com/bide-ai/bide/cmd/bide-view@latest still resolves to the stub, which prints that it moved; install cmd/bide and run bide view.
Repo-only (never tagged; they keep their replace directives): examples/approval, examples/plan, examples/mcp, examples/observability, examples/govern, examples/hsm-signing, examples/sso-certs, examples/stripe-refund, the four emulator and fake-server test modules, integration and benchmarks.
The exported API of every package in the published modules is listed in the generated SDK API reference, one page per module (the core module, one per package), with each package's stability label. The reference reads the Repo-only and command lists from scripts/release.sh, so a module added to the release is documented and a repo-only module is not.
The procedure is in CONTRIBUTING.md. The Lint job fails if a module is in neither list, and a pushed nested tag fails its check if the tagged go.mod still requires v0.0.0 or replaces a bide module.