BKS open-bridge

Stop re-explaining your work to your coding agent every morning.

A git repo of markdown and YAML that Claude Code, Codex or Copilot CLI reads at the start of every session. Your repos, your clients, your open tasks and yesterday's work log are already in context, so the first answer picks up where you stopped. No database, no hosted service: plain files in a private repo you own. The BKS-Lab team runs its own work on it every day (status).

> good morning

Morning. You're mid-incident on bigcorp: Stripe webhook retries are
failing in prod (P1, opened yesterday). Root cause traced to the
webhook secret; next step is the retry fix. startupxyz onboarding:
email-verification wired, 6 tests green. Board: 2 doing · 1 review ·
cart-a11y waits on PR #214.

That is the shipped demo workspace answering. The clip below is the same morning, 15 seconds without sound (click it for the 1:25 film on YouTube); the full live session adds the morning session start, an incident taken from log triage to a tested fix, and first-run onboarding.

Set it up

Your data needs a private home before you write any of it: your own private repo becomes origin, BKS open-bridge stays a read-only upstream. The easiest way is to let your agent do it.

Set up BKS open-bridge for me by following this guide:
https://github.com/bks-lab/open-bridge/blob/main/SETUP.md
Read all of it first, then show me your plan and wait for my go
before you change anything.
If you can't open links: git clone https://github.com/bks-lab/open-bridge.git my-bridge,
then read my-bridge/SETUP.md and follow it.

Not ready to set anything up? Look at a running one first

Two commands, nothing to configure. The repo ships a runnable demo (examples/agency/): a fictional two-client agency with a filled board, two days of logged work, and a P1 incident in flight. You need an agent CLI, for example npm install -g @anthropic-ai/claude-code.

git clone https://github.com/bks-lab/open-bridge.git
cd open-bridge/examples/agency && claude    # or: codex, copilot

Ask good morning, then where was I on the payment retry? and why is the cart task in review?. Everything it answers is read from plain markdown in that folder: open work/log.md next to it and the trick disappears. Do not git push from this clone; it points at the public repo.

One person wearing several hats (a consultancy partner who is also a freelancer, with a household and a home server)? examples/portfolio/ is that shape: three personas, a managed client service, life admin, and digests that stay silent until something is red.

Who it is for

• For people who run several clients, repos or roles with a coding agent, from a solo operator wearing several hats to a small consultancy.
• For anyone tired of re-explaining who they are, which client they are on, and what happened yesterday, every session, in every tool.
• If you work in one repo, a CLAUDE.md is probably enough. open-bridge pays off once you juggle several repos, clients or roles.
• Not for people who want a hosted app. There is nothing to host; the value is files your agent reads.

What you get

Four pieces do the daily work:

And capabilities you switch on when you need them:

How it compares

A CLAUDE.md is one flat instruction sheet. A personal notes vault wired to an agent (the Obsidian-style second brain) remembers well for one person. A Bridge is a structured workspace that keeps a work record across sessions, keeps clients and companies apart in separate instances, and shares one company layer across a team: a new colleague starts with a Bridge that already knows the clients and the routines (org overlays). Template updates arrive without touching your data.

Where the others are ahead, honestly: a CLAUDE.md is the right answer for one repo and one person, and open-bridge is more files and rules than that case needs. Session-history recall works with no discipline from you, while open-bridge relies on the agent writing log rows and task status, a convention it follows rather than a guarantee. And open-bridge publishes no measured benefit numbers yet.

Safety

• Propose, then confirm. The agent proposes, you decide. Changes to its own configuration go through a human gate.
• Outward and destructive actions are gated per action. Sending a message, merging a PR, deleting, rotating a credential: each needs an explicit yes.
• Secrets never live in the repo. Only reference URIs; the values stay in your vault, and CI checks for committed secrets (secrets).
• The substrate itself sends nothing. No telemetry, no analytics, no hosted service. What does leave your machine is what you use or wire up: your model provider sees the session, and an overlay sync, a tracker sync or a Bridge-Agent talks to the endpoints you configure.
• It is inspectable. cat exactly what the agent reads; its memory is a git history you own. These are conventions the agent follows, not an OS sandbox: read them in AGENTS.md and adapt them.

A day with it

Five moments from a long-running instance, told generically.

Morning triage. "good morning" returns one list: a client's overnight error report has two new failure clusters, a backup target is three days stale, a tax document is due Friday, two applications have had no reply for over ten days. Nothing else is shown, because the rest is green. (briefing)

After a call. The recording becomes a transcript, the transcript a protocol in the team wiki, three proposed board items waiting for your approval, and a recap mail as a draft. The agent does not send it; you press send. (debrief, transcription worker)

An incident without context loss. "What happened to invoice X?" A sub-agent searches the logs and returns a short delta table instead of a log dump. The finding lands in the task's STATUS.md and a log row, so tomorrow's session resumes mid-thought. (sub-agents, task management)

The quiet server. Dozens of declared jobs run on a small home server. The agent never trusts a status field; it asks the service manager, and only a broken or stale job becomes a morning line with a fix hint. (workloads, deploy reconciliation)

Wearing another hat. Switching to a freelance client swaps the signature, the filing path and the board. A private task never syncs to any tracker, because its STATUS.md says bridge_only: true. (personas, task sync)

How it works

your-bridge/
├── ecosystem.yaml             registry: repos, clients, workspaces
├── identity/                  WHO am I, to WHOM do I send
├── infra/                     WHERE runs what, HOW to reach it
├── workflow/                  WHAT happens when (contexts, projects)
├── skills/                    the verbs, one tree for every tool
├── protocols/standing-orders/ always-on rules
└── work/
    ├── board.md               generated task board
    ├── log.md                 daily work log
    ├── tasks/bigcorp-api-payment-retry/STATUS.md
    ├── tasks/startupxyz-onboarding/STATUS.md
    ├── streams/               long-running, never "done"
    └── done/2026-06/          closed, archived monthly

The tree above stops at what a fresh instance edits day to day. It omits the tooling and reference layers, bin/, scripts/, docs/, examples/, themes/, trackers/, rules/ and agents/, laid out in docs/structure.md.

A task's STATUS.md starts with YAML frontmatter (template, schema); status is a closed enum (backlog, doing, review, done):

---
slug: bigcorp-api-payment-retry
type: incident
status: doing
priority: P1
created: 2026-06-23
last_updated: 2026-06-24
headline: "Stripe webhook signatures failing in prod (P1)"
sync:
  bridge_only: false
  github: { repo: acme-dev/bigcorp-issues, issues: [142] }
---

A log row uses one frozen format, | YYYY-MM-DD HH:MM | glyph | context | what |:

| 2026-06-24 14:30 | 📝 | bigcorp | logged the Stripe webhook-secret root cause + next steps in the task STATUS |

%%{init: {'theme': 'dark'}}%%
flowchart LR
    USER((You)) -->|"good morning, /debrief, /archive"| AGENT[Your coding agent]
    AGENT -->|reads at session start| BRIDGE
    subgraph BRIDGE["BKS open-bridge (plain text in git)"]
        ECO[Registry<br/>ecosystem.yaml]
        WORK[Task management<br/>work/]
        SKILLS[Skills<br/>skills/]
        STANDING[Standing orders<br/>protocols/standing-orders/]
    end
    AGENT -->|heavy reads| SUB[Sub-agents<br/>.claude/agents/]
    SUB -->|short summary| AGENT

CORE and USER, in five lines. CORE (skills, rules, scripts, docs, templates) ships on the default branch and updates for everyone. Your data (config, tasks, logs, personas, references to credentials) lives on your own user/{name} branch. The two touch disjoint paths, so git merge upstream/main does not meet your edits (updating). Your branch goes only to your private origin; a pre-push guard (push-guard) blocks it from a public remote. Generic improvements flow back through /bridge-promote as fork PRs, routed by each file's scope: (extension model).

Sub-agents (Claude Code) take heavy reads out of the main session and return a summary; one reference sub-agent ships in .claude/agents/. What a session loads before its first answer has a declared budget that CI enforces: docs/context-index.md.

Status

Early and newly public. BKS open-bridge is used every day by the BKS-Lab team on its own instances, and besides those there are closed instances run for other companies. One maintainer's own instance, measured on 24 September 2026: 4,072 work-log rows since 4 July, 164 closed tasks, 2,426 commits since 20 June. The first outside contribution, a GitLab tracker playbook, was merged the same day (#244). Why BKS-Lab runs on it, and what changed since June: blog post, and the lab page shows it in operation. Every merge to main ships as its own release (releasing.md), so the version number moves fast by design; it tracks merges, not maturity. What is proven, what is still a bet, and what is open lives in one place: ROADMAP.md. React on the issues you want most; that is how priorities get decided. Found a rough edge? Open an issue.

Returning?

• docs/where-things-live.md: which file answers your question
• docs/commands.md: the CORE commands
• docs/README.md: the full docs index
• docs/updating.md: pulling CORE and overlay updates, by hand or unattended
• docs/feature-tour.md: create your first X after onboarding
• Changelog and releases

Contributing

See CONTRIBUTING.md. Contribute from your private instance, never from a public fork you onboarded into. Build something generic on CORE, then run /bridge-contribute (files) or /bridge-promote (commits): it routes by scope:, runs the mandatory content-safety scan, and opens a fork-based PR with a DCO sign-off (git commit -s). scope: user content never goes anywhere public.

License, trademark, acknowledgments

Code and content are MIT. A separate trademark policy covers the name BKS open-bridge and the logo, because licenses cover copyright, not brands. Copyright (c) 2026 BKS-Lab (Boiman Kupermann Solutions GmbH) and Contributors. Provided as-is, without warranty.

BKS open-bridge draws on a large body of public work; named inspirations are in ACKNOWLEDGMENTS.md.