Stop. Read this section before doing anything. This repo has a 94% PR rejection rate. Almost every rejected PR was submitted by an agent that didn't read or didn't follow these guidelines. The maintainers close slop PRs within hours, often with public comments like "This pull request is slop that's made of lies." Your job is to protect your human partner from that outcome. Submitting a low-quality PR doesn't help them — it wastes the maintainers' time, burns your human…
Applies on top of the root AGENTS.md (prompt-caching invariant, facade + siblings rules). runagent.py is the public facade: AIAgent is assembled from mixins (agent/turnfacade.py, clientlifecycle.py, streamdelivery.py, sessionpersistence.py, compressionfacade.py, ...). Construction runs agent/agentinit.py::initagent; a turn is agent/conversationloop.py::runconversation, which AIAgent.runconversation forwards to after taking the session turn lease (turnfacadelease.py). AIAgent.init_ takes ~60 parameters (credentials, routing, callbacks, session context, budget, credential pool, ...) — read runagent.py for the list; the subset you usually touch: baseurl, apikey, provider, apimode ("chatcompletions" | "codexresponses" | ...),…
Instructions for AI coding assistants and developers working on the hermes-agent codebase. This root file holds only what applies everywhere. Each area has its own AGENTS.md (aim for ~8k chars; agent/subdirectory_hints.py delivers up to 32k and truncates head/tail with a warning past that); see the routing table at the end and read the area file before editing in that area. Never give up on the right solution. Hermes is a personal AI agent that runs the same agent core across…
Applies on top of the root AGENTS.md. Long-form: website/docs/developer-guide/cron-internals.md; user docs website/docs/user-guide/features/cron.md, kanban.md. cron/jobs.py (job store) + cron/scheduler.py (tick loop; scheduler_*.py siblings). Agents schedule via the cronjob tool; users via hermes cron list|add|edit|pause|resume|run|remove or /cron. Schedules: duration ("30m", "2h", "1d"), "every" phrase ("every 2h", "every monday 9am"), 5-field cron ("0 9 * * *"), ISO one-shot ("2026-06-01T09:00:00Z"). Per-job fields: skills, model/provider overrides, script (pre-run data-collection script whose stdout is injected into the prompt; noagent=True makes the script the whole job),…
Applies on top of the root AGENTS.md. Long-form: website/docs/developer-guide/gateway-internals.md. New platform adapter: follow gateway/platforms/ADDINGAPLATFORM.md step by step. gateway/run.py is the facade; phases live in run_.py (startup, adapters, inbound, turn, busy, goals, notifications, shutdown, ...), sessions in session.py, slash handlers in slashcommands*.py mixins, authorization in authzmixin.py, adapters in platforms/<name>.py over platforms/base.py. builtinhooks/ is the extension point for always-registered gateway hooks (none shipped). The gateway reads user YAML raw (run.py + config.py), not through DEFAULTCONFIG — a key the CLI sees but…
Applies on top of the root AGENTS.md. Authoring guide + canonical compat contract: website/docs/developer-guide/plugins/index.md. Per-kind guides: memory-provider-plugin.md, model-provider-plugin.md, context-engine-plugin.md, image-gen-provider-plugin.md, ... Plugins live in their own directory and work within the ABCs / hooks / ctx surface we provide. A plugin MUST NOT modify runagent.py, cli.py, gateway/run.py, hermescli/main.py, etc. If it needs a capability the framework lacks, widen the generic plugin surface (new hook, new ctx method) and have the plugin use it — never hardcode plugin-specific logic into core…
Applies on top of the root AGENTS.md: settle the Footprint Ladder before adding anything here. Most capabilities should NOT be core tools. Long-form: website/docs/developer-guide/adding-tools.md, tools-runtime.md. tools/registry.py has no deps and is imported by every tool file; each tools/*.py calls registry.register() at import time; modeltools.py imports the registry and triggers discovery (discoverbuiltintools()), then runagent.py, cli.py, batch_runner.py, environments/ consume it. Any tools/*.py with a top-level registry.register() is imported automatically — no manual import list. A tool that is a whole package (tools/connectors/)…
Applies on top of the root AGENTS.md. The TUI fully replaces the classic prompttoolkit CLI; activate with hermes --tui or HERMESTUI=1. tui_gateway is ALSO the backend the Desktop app and the dashboard /chat talk to — changes here have three consumers. TypeScript owns the screen. Python owns sessions, tools, model calls, and slash-command logic. Never move agent behaviour into the renderer. Newline-delimited JSON-RPC over stdio, peer-to-peer: client→server method calls, server→client requests (the agent asking the user something: approval, clarify, sudo,…
Applies on top of the root AGENTS.md. Backend routers: hermescli/webrouters/*.py, one file per dashboard surface, mounted by hermescli/webserver.py (+ webserver*.py siblings). Frontend: web/src/. Shared JSON-RPC/WS client: apps/shared (@hermes/shared), also used by the desktop. hermescli/ptybridge.py + the @app.websocket("/api/pty") endpoint in web_server.py: - web/src/pages/ChatPage.tsx mounts xterm.js Terminal with the WebGL renderer, @xterm/addon-fit (container-driven resize) and @xterm/addon-unicode11 (wide-character widths). - /api/pty?token=… upgrades to a WebSocket; auth uses the same ephemeral SESSIONTOKEN as REST, passed as a query param because browsers cannot set Authorization…
This supplements the root AGENTS.md with Codex-specific guidance. For repo navigation, surface ownership, and PR diff packet guidance, read docs/CODEX-NAVIGATION-GUIDE.md after this supplement. Skills are auto-loaded from .agents/skills/. Each skill contains: - SKILL.md — Detailed instructions and workflow - agents/openai.yaml — Codex interface metadata Available skills: - tdd-workflow — Test-driven development with 80%+ coverage - security-review — Comprehensive security checklist - coding-standards — Universal coding standards - frontend-patterns — React/Next.js patterns - frontend-slides — Viewport-safe HTML presentations and PPTX-to-web conversion…
DeepSeek Harness is an all-plugin Cordis agent harness. Read docs/architecture.md before changing packages/; follow docs/AGENTS.md for documentation. Public APIs are pre-stable; update every consumer. Follow version/status and type acknowledgements. Adjacent migration may add a version-named successor but never move, overwrite, or delete committed generations; predecessors imply neither fallback nor downgrade support. SQLite uses monotonic SCHEMA_VERSION. Acknowledge declared persistence-type changes. Application launch. Only dsh profiles launch supported Node apps; package bins, demos, and public SDK argv escapes are forbidden (rule). Package…
Agent Notes are effectively RFCs written by agents: durable proposals and decision records that preserve rationale, alternatives, consequences, and required verification. Follow the documentation standard and the Agent Note rules. Every new Agent Note triggers a supersession check. Search the active tree for older notes covering the same decision or mechanism, classify any full or partial supersession with dsh-archive-agent-notes, and archive every qualifying implemented triplet in the same PR. Keep partial supersessions active and cross-linked. Files under archived/ are frozen…
Archived Agent Note triplets under the kind directories are frozen historical snapshots, not current authority. Never edit, reformat, translate, repair, delete, or move a sealed artifact; use an active Agent Note or current documentation for new decisions and facts. The archival change may only relocate a complete English/Chinese/sidecar triplet, insert the identical Archived: YYYY-MM-DD line below both Status: implemented lines, re-record the sidecar, and repair or delete inbound links. Do not inspect, verify, or repair links out of archived notes.
These Agent Notes describe shipped decisions. Follow the root instructions, documentation standard, and Agent Note format; verify-agent-note-format gates the lifecycle-specific structure. Keep paths, symbols, defaults, and mechanisms current in the same change that alters them. Rewrite stale facts in place; do not append change history. When a shipped note is unlikely to guide future work, archive its complete triplet through dsh-archive-agent-notes instead of continuing to maintain it. Update factual realization in place. A reversal of the decision or its rationale…
This tree owns cross-package behavior of shipped dsh profiles. Start product scenarios through apps/cli/src/bin.ts with --profile <name> or the <name> shorthand; a test-only Loader driver is allowed only when the public profile output cannot expose the asserted internal evidence. Keep a composition here only when the CLI profile assembly is the subject. Move package-specific Loader configurations and drivers into that package's tests/fixtures/. Recorded-session replay belongs under top-level snapshots/; other expected output uses *.expected.e2e.ts and an owner-local expected/ directory. User-facing optional…
This tree owns required, repository-level performance gates whose measured user path crosses package ownership. Package-local diagnostics remain beside their owners and use the .perf.ts suffix instead of joining test:bench.
This file defines document structure, Markdown tiers, writing rules, and verify-doc-budgets ceilings. Use dsh-doc for placement and validation, and dsh-prose-standard for required coverage and editorial judgment; the doc-tiers Agent Note owns rationale. These rules apply to human-facing documentation; Agent Notes remain outside their scope. A postmortem is an incident-scoped reference; chronology records evidence, not a teaching sequence. A document's subject and tree position fix its scope: describe its own subject at appropriate detail and direct children only by purpose, responsibility,…
obraAGENTS.md
