Repo-local .honcho configuration overlay

[outpoints]

Repo-local .honcho configuration overlay

Adds an optional per-project configuration overlay: a .honcho/config.json inside a repository overrides the global ~/.honcho/config.json for that working tree.

Why

Honcho gives Claude Code a single global workspace, so for anyone working across multiple projects, every project's messages, tool activity, and derived conclusions land in the same workspace and shape one shared representation. There's no way to say "this repository's memory belongs to workspace X," which causes cross-project bleed — unrelated work clouding a workspace you'd rather keep focused. This overlay makes per-project isolation possible, declaratively and per repo, without putting credentials in the repo.

How it works

• Overlay, not replacement. The global config resolves exactly as before; the repo-local file is layered on top and only the fields you set are overridden. apiKey, endpoint, peerName, and the rest inherit from the global config, so the repo file is usually just { "workspace": "my-project" } — no secrets in the repo, safe to commit and share across machines.
• Discovery walks up. The nearest .honcho/config.json at or above the working directory wins (the global ~/.honcho is never treated as repo-local). One file at the project root covers the whole tree; another in a subtree scopes that subtree. Honored by all hooks and the MCP server.
• Read-only and non-contaminating. The plugin never writes the repo file, and a repo-local override can never be persisted into or leak out of the global config. get_config reports when a repo-local config is active; set_config directs edits to the repo file.
• Sessions anchor to the project, not the cwd. Claude Code reports whatever subfolder it's in as the working directory, which would otherwise split one project into a session per subfolder. With a repo-local config the session anchors to the project root. sessionName pins an exact name; opt-in splitSubmodules gives each nested git submodule its own session while inheriting the parent's workspace, since submodules are independent codebases you may want tracked separately without adding a file to each.
• Per-workspace context cache. The at-prompt memory hint is served from a cached snapshot, now keyed by workspace so concurrent sessions on different workspaces never read each other's context.

Compatibility

Entirely additive and opt-in: with no .honcho/ present, config resolution, the hook lifecycle, caching, and the MCP server behave exactly as before. The overlay is a thin layer in front of loadConfig() and existing functions keep their semantics. No version or manifest changes; bunx tsc --noEmit passes.

Verification

Exercised end-to-end against a self-hosted Honcho instance: a repo override routes that project's messages to its own workspace, isolated from the global workspace; the default path still routes to the global workspace and leaves the global config byte-for-byte unchanged; subfolders consolidate to one project-root session; splitSubmodules gives nested git repos (including .git-file submodules) their own session while inheriting the workspace; and concurrent workspaces read only their own cached context. Verified via direct resolution checks and by running the real hooks as subprocesses.

Summary by CodeRabbit

Release Notes

• New Features

  • Per-project configuration support: Place .honcho/config.json in your repository to override selected fields from global config while inheriting the rest.
  • Workspace-scoped context caching to prevent cross-workspace context sharing.
  • Session naming anchored to project root with optional fixed session names.
  • Submodule handling via splitSubmodules configuration option.

• Documentation

  • Added comprehensive guide for per-project configuration with usage examples and best practices.

[coderabbitai]

Warning

Review limit reached

@outpoints, we couldn't start this review because you've used your available PR reviews for now.

Your plan includes 1 review of capacity. Refill in 18 minutes and 46 seconds.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more review capacity refills, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than trial, open-source, and free plans. In all cases, review capacity refills continuously over time.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: cda35a56-395f-4008-8d2c-360ae404626c

📥 Commits

Reviewing files that changed from the base of the PR and between 1f55abc and 82aa11e.

📒 Files selected for processing (3)

• CHANGELOG.md
• README.md
• plugins/honcho/src/mcp/server.ts

Walkthrough

This PR implements repository-local configuration overlays at .honcho/config.json, enabling per-project config overrides that inherit unset fields from global config. It adds workspace-scoped context caching, anchors session names to the project root, guards against persisting local overrides globally, and routes all MCP tools through per-request active config for proper scoping.

Changes

Repository-Local Configuration Support

Layer / File(s)	Summary
Config Interface & Discovery Helpers plugins/honcho/src/config.ts	Adds sessionName and splitSubmodules optional fields to HonchoCLAUDEConfig interface. Imports dirname and resolve for path operations. Introduces comprehensive repo-local discovery system: findLocalConfigDir() walks filesystem for .honcho/ directory, findNearestGitRoot() locates nested git roots, context setters/getters manage the active local config directory, hasLocalConfig() and isLocalConfig() predicates check state, and applyLocalConfigOverrides() reads the repo JSON file and merges only whitelisted fields onto resolved config before marking it as local via non-enumerable symbol.
Config Loading & Persistence Guards plugins/honcho/src/config.ts	initHook() derives a candidate working directory from workspace roots or process cwd, then registers it via setLocalConfigContext(). loadConfig() routes both file-loaded and env-only configs through applyLocalConfigOverrides(), ensuring repo-local overlays are always applied. saveConfig() returns early when config is marked local, preventing repo-local overrides from leaking into the global ~/.honcho/config.json. setSessionForPath() returns early when any repo-local config is active, disabling per-cwd session persistence during overlay mode.
Session Name Anchoring to Project Root plugins/honcho/src/config.ts	getSessionName() shifts session identity from the provided cwd to the .honcho/ project root when repo-local config is active. With splitSubmodules enabled, it anchors further to the nearest nested git root within that project. An explicit repo-local sessionName field pins the entire project to a single deterministic session name, optionally peer-prefixed. Git branch capture and session base derivation now use the anchored directory instead of raw cwd.
Workspace-Scoped Context Cache plugins/honcho/src/cache.ts	Refactors the context cache from single-slot userContext/claudeContext fields to per-workspace maps (userContextByWorkspace, claudeContextByWorkspace) keyed by workspace name derived from config with _global fallback. Introduces typed ContextCacheEntry with fetchedAt timestamp. Updates import to include loadConfig(). Extends known-keys allowlist for migration. All cache accessors (getCachedUserContext, setCachedUserContext, getStaleCachedUserContext, isContextCacheStale) now read/write workspace-scoped entries with TTL checks. Cache-clearing functions reset all per-workspace maps and remove legacy fields.
MCP Tool Server Per-Request Config Routing plugins/honcho/src/mcp/server.ts	Imports local config helpers (setLocalConfigContext, hasLocalConfig, getLocalConfigPath). get_config handler detects repo-local config and includes localConfig metadata (active status and path) in response; adds warning notice when local config is active. set_config returns an error-like response when repo-local config is active, advising the user to edit the local file directly instead. Tool handler sets local context from request cwd, selects activeConfig/activeHoncho per request. Peer-only tools (list_conclusions, delete_conclusion) compute observation mode and scope from activeConfig. Session tools derive observation mode, peer selection, and chat/context targets from activeConfig. search tool routes through activeHoncho instead of startup honcho. chat tool prefers activeConfig.reasoningLevel. create_conclusion scopes conclusions under activeConfig.peerName.
Documentation CHANGELOG.md, README.md	CHANGELOG.md adds unreleased feature entry documenting the repo-local config overlay with inheritance rules, read-only file semantics, get_config/set_config behavior, session anchoring to project root, optional sessionName pinning, opt-in splitSubmodules for submodules, and workspace-scoped context caching. README.md introduces "Per-Project Config (repo-local .honcho/)" section under Configuration, explaining discovery, inheritance, session naming and routing, submodule handling, security guidance (keep secrets global), read-only expectations, and provides full and minimal JSON configuration examples.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related issues

• #30: This PR directly implements the repo-local .honcho/config.json feature that was proposed in issue #30, including project-config discovery and overlay in config.ts, MCP handling of read-only local overrides, and workspace-scoped caching.

Poem

🐇 A warren of configs, now split near and far,
Per-project overrides beneath each repo's star,
Sessions anchored home to the .honcho/ ground,
Workspace caches bloom where no cross-talk is found,
Global secrets safe while the local dance plays. 🎭

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 58.06% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Repo-local .honcho configuration overlay' accurately and concisely summarizes the main change: adding a per-project configuration overlay mechanism. It is specific, clear, and directly reflects the primary objective of the PR.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@CHANGELOG.md`:
- Line 12: The CHANGELOG line incorrectly states that set_config directs edits
to the repo file; update the wording so it matches the implementation: in
local-config mode the MCP server rejects set_config writes and users must edit
.honcho/config.json manually. Edit the sentence referencing get_config and
set_config to note that get_config reports when a repo-local config is active
and that set_config does not write repo-local configs (MCP rejects the write) —
users are instructed to update .honcho/config.json by hand instead.

In `@README.md`:
- Around line 209-210: Update the README wording to reflect current behavior:
change the sentence about set_config to state that when a repo-local config is
active (as shown by /honcho:status) the plugin treats configs as read-only and
set_config returns a read-only response (edits must be made directly to the repo
file) instead of implying set_config still writes; also correct the cache-key
description to state caches in ~/.honcho are keyed by workspace (not by
directory) and explain that workspace-scoped keying prevents cross-project
collisions. Reference the terms set_config, /honcho:status, and ~/.honcho when
making these text edits so the doc accurately matches implementation.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 5d25dad5-f1dc-4fc7-adc5-2c1c4dae6f21

📥 Commits

Reviewing files that changed from the base of the PR and between 0813ebd and 1f55abc.

📒 Files selected for processing (5)

• CHANGELOG.md
• README.md
• plugins/honcho/src/cache.ts
• plugins/honcho/src/config.ts
• plugins/honcho/src/mcp/server.ts