Architecture-quality audit notes from hermescheck

[huangrichao2020]

Hi maintainers — this is a friendly architecture-quality audit note, not a security report.

I've been building hermescheck, a small open-source scanner that reviews AI agent runtimes and gateway-style systems for recovery boundaries, schema drift, memory/state ownership, and other long-running maintainability risks. I ran it against ccNexus because this repo has a compact but real gateway/runtime surface across endpoint routing, request transformation, session handling, and persistent config/storage.

Three runtime/architecture notes looked worth sharing:

1. Endpoint and transformer compatibility looks very flexible, but the contract appears mostly config-driven rather than pinned.
   internal/proxy/endpoint_resolver.go lets callers steer endpoints through headers, query params, and @endpoint/model syntax, while internal/proxy/request.go dynamically maps that choice into different upstream protocol shapes. That is powerful, but it also means backend API drift can become a runtime surprise unless there is a stronger reviewed compatibility boundary around endpoint + transformer combinations.

2. Session continuity appears to depend on an external file-layout contract.
   internal/session/session.go reads session state and aliases from ~/.claude/projects/... and derives summaries directly from those JSONL files. That works today, but architecturally it makes continuity depend on another tool's on-disk structure rather than on an app-owned resumability contract, which may get brittle over time.

3. Portable config and runtime-secret state look only partially separated.
   internal/storage/sqlite.go explicitly defines safeConfigKeys for cross-device backup/restore, and internal/service/backup.go persists and restores that configuration. The intent is clear, but it may still help to make the portable-config vs device/session-credential boundary even sharper so backup/restore behavior stays predictable as more auth and provider types are added.

None of the above is meant as "you must change this"; it just looked like a useful maintainer-facing architecture snapshot from an external pass.

Repo for the tool: https://github.com/huangrichao2020/hermescheck

If this isn't useful, feel free to close and I won't take it personally.

[lich0821]

Thanks, noted.

…

On Wed, May 6, 2026 at 5:52 PM Huang richao ***@***.***> wrote: *huangrichao2020* created an issue (lich0821/ccNexus#128) <#128> Hi maintainers — this is a friendly architecture-quality audit note, not a security report. I've been building hermescheck <https://github.com/huangrichao2020/hermescheck>, a small open-source scanner that reviews AI agent runtimes and gateway-style systems for recovery boundaries, schema drift, memory/state ownership, and other long-running maintainability risks. I ran it against ccNexus because this repo has a compact but real gateway/runtime surface across endpoint routing, request transformation, session handling, and persistent config/storage. Three runtime/architecture notes looked worth sharing: 1. Endpoint and transformer compatibility looks very flexible, but the contract appears mostly config-driven rather than pinned. internal/proxy/endpoint_resolver.go lets callers steer endpoints through headers, query params, and @endpoint/model syntax, while internal/proxy/request.go dynamically maps that choice into different upstream protocol shapes. That is powerful, but it also means backend API drift can become a runtime surprise unless there is a stronger reviewed compatibility boundary around endpoint + transformer combinations. 2. Session continuity appears to depend on an external file-layout contract. internal/session/session.go reads session state and aliases from ~/.claude/projects/... and derives summaries directly from those JSONL files. That works today, but architecturally it makes continuity depend on another tool's on-disk structure rather than on an app-owned resumability contract, which may get brittle over time. 3. Portable config and runtime-secret state look only partially separated. internal/storage/sqlite.go explicitly defines safeConfigKeys for cross-device backup/restore, and internal/service/backup.go persists and restores that configuration. The intent is clear, but it may still help to make the portable-config vs device/session-credential boundary even sharper so backup/restore behavior stays predictable as more auth and provider types are added. None of the above is meant as "you must change this"; it just looked like a useful maintainer-facing architecture snapshot from an external pass. Repo for the tool: https://github.com/huangrichao2020/hermescheck If this isn't useful, feel free to close and I won't take it personally. — Reply to this email directly, view it on GitHub <#128>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AU5NR2ELX634IZLN7HMHHTL4ZMDN5AVCNFSM6AAAAACYS2UAYWVHI2DSMVQWIX3LMV43ASLTON2WKOZUGM4TAMZYG42DOMY> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>. You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>