feat: workspace config file — knowledge base path and session startup settings

[melfebulu]

Summary

When two agents (Claude + Codex) start a collaboration session, there is currently no way to configure session-level settings per workspace. This issue proposes a workspace config file that AgentBridge reads at session startup, starting with a knowledge base path setting and designed to be extended over time.

Motivation

We have been using a shared knowledge base directory (cowork/) that stores infrastructure references, service documentation, runbooks, and work logs accumulated across collaboration sessions. Currently there is no way for AgentBridge to know where this knowledge base is, or to inject its contents into the session automatically.

More broadly, different projects and workspaces have different collaboration needs — roles, message filtering preferences, startup context — and there is no place to express these per-workspace today.

Proposed Solution

Add support for a workspace config file (.agentbridge.json) that AgentBridge reads when a session starts. The file lives in the collaboration working directory, so it travels with the project.

Initial config schema

{
  // Knowledge base: paths to inject into agent context at session startup
  "knowledgeBase": {
    "paths": [
      "./cowork",            // local directory — all .md files are read
      "/absolute/path/cowork"
    ],
    "include": ["**/*.md"],  // glob filter
    "maxFileSizeKb": 50,     // skip files larger than this
    "injectAs": "system"     // "system" | "user" message
  },

  // Role overrides (optional, overrides built-in defaults)
  "roles": {
    "claude": "Reviewer, Planner, Decision Maker",
    "codex": "Implementer, Executor, Verifier"
  },

  // Delivery mode override for this workspace
  "deliveryMode": "auto",        // "push" | "pull" | "auto"

  // Minimum marker level to forward: "important" | "status" | "all"
  "minMarkerLevel": "status",

  // Short context injected at session start (workspace-specific instructions)
  "startupContext": "This workspace manages the hk-dalaxy-tech server cluster."
}

Behavior at session startup

1. bridge.ts looks for .agentbridge.json in the current working directory (walk up to git root if not found)
2. If knowledgeBase.paths is set, read matching files and inject a summary into Claude's system context and optionally Codex's first turn
3. Role overrides and filter settings apply for the session duration
4. startupContext is prepended to the first message Claude receives

Extensibility

The schema is intentionally forward-compatible — unknown keys are ignored. Future additions being considered:

Setting	Description
knowledgeBase.remoteSync	Pull from a remote path via SSH before injecting
roles.thirdAgent	Role definition for a third agent (e.g. Gemini, v2 multi-agent)
sessionNaming.prefix	Auto-generate session IDs with a workspace prefix
notifications.user	Control which events are surfaced to the human
turnCoordination.timeoutMs	Per-workspace turn timeout override
knowledgeBase.autoSync	Write back new learnings to the knowledge base at session end

Implementation Notes

• Config file is optional — all fields have defaults, fully backwards compatible
• Schema validation should be lenient (unknown keys ignored) for forward compatibility
• Respect maxFileSizeKb to avoid blowing context on large files
• A --no-config CLI flag should allow opting out for sessions where startup injection is unwanted
• The config should merge with (not override) any global/user-level AgentBridge settings

Background

This issue originated from real-world usage: Claude + Codex built a shared cowork/ knowledge base containing infra docs, service runbooks, work logs, and server-specific notes across multiple collaboration sessions. At the start of each new session, both agents start cold with no awareness of this accumulated knowledge — they have to re-read the files manually. A workspace config file would close this gap automatically.

[raysonmeng]

Thanks for this proposal, and apologies for the very slow first response — closing the loop now with a status update, because part of what you asked for has since shipped:

• The workspace config file exists now: AgentBridge reads .agentbridge/config.json at session startup (config-service), currently covering ports, idle shutdown, turn coordination and budget-coordination settings. The extensible per-workspace config infrastructure this issue proposed is in place.
• The knowledge-base path setting specifically is not implemented yet. Injecting a knowledgeBase path into both agents' collaboration context at startup would slot naturally into the existing marker-section injection (abg init writes the AgentBridge block into CLAUDE.md/AGENTS.md) — a config key + one line in the generated context is most of the work.

If your cowork/ workflow is still active, a short note on what the agents should be told about the knowledge base (just the path? read-before-task conventions?) would shape the key's design. Keeping this open as the tracking issue for the knowledge-base setting.

中文摘要：工作区配置文件已落地（.agentbridge/config.json），issue 的基础设施部分已实现；knowledge base 路径键尚未做，天然落点是 init 的 marker 注入内容。保持 open 跟踪该键的设计，欢迎补充使用约定。