How h4ckforge/sentinel works
1. This repo is not an application server; it is an agent package.
Sentinel is mainly a collection of Markdown prompt assets plus a small Python persistence utility. The runtime that actually hosts the LLM is external (Hermes Agent today, but the repo is intentionally model-agnostic).
2. Core control plane: the system prompt.
sentinel_soul_v1.3.md is the active system prompt and appears to be the primary brain of the agent. The README describes it as a 6-layer prompt covering identity, conduct, decision rules, tone, security behavior, and meta-instructions.
3. Task execution is organized as skills.
skills/ contains the operational modules the agent can invoke: /plan, /recon, /enum, /exploit, /post, /report, /analyze, /rt-llm, /state, /handoff, and /checkpoint. Each skill is a SKILL.md document, so the skills are prompt-level behavior specs rather than code libraries.
4. The engagement lifecycle is encoded as phases.
The skills map directly to a red-team workflow: planning → recon → enumeration → exploitation → post-exploitation → reporting. The architecture should show these as sequential but not strictly linear, since /analyze, /state, /handoff, and /checkpoint can be used at any point.
5. Session state is a shared contract across all skills.
The README defines a common state schema: session_id, mode, target, last_tool, user_level, recon_done, phase_complete, active_skill, pending_actions, explained_concepts, and findings. skills/recon/SKILL.md is noted as the place where this schema is defined, and all other skills read/extend it.
6. Persistence is externalized into SQLite through a narrow boundary.
The agent itself emits plain-text CHECKPOINT blocks; it does not write structured storage directly. The skills/checkpoint/scripts/ utilities are the bridge to persistence: init_db.py initializes the SQLite schema, checkpoint.py parses a checkpoint block and writes it, and recover.py reconstructs the latest session state back into a checkpoint block.
7. The database is a separate runtime artifact, not part of the prompt layer.
sentinel.db is the persistent session store, with the default path configurable via SENTINEL_DB. This creates a clean split between ephemeral model context and durable engagement memory.
8. Input/output boundary for checkpoints is text-based.
The checkpoint format is a structured plain-text block with explicit fields and an END_CHECKPOINT marker. That means the architecture should show the LLM emitting text, the Python script parsing that text, and SQLite storing the resulting state.
9. Operator guidance and workflow conventions live outside the agent loop.
operator-guide.md documents wiki/Obsidian conventions, which suggests a human-facing operational layer for organizing knowledge and engagement notes. This is adjacent to the agent but not part of the core execution pipeline.
10. Versioned prompt documents show prompt evolution, not separate app versions.
The presence of sentinel_soul_v1.0.md through v1.3.md implies iterative prompt refinement. Only v1.3 is active; the others are historical references for prompt evolution.
11. Dependencies and infrastructure are intentionally minimal.
The repo uses Python 3.10+ and only stdlib modules for the scripts (sqlite3, argparse, json, re). There is no application framework, API server, or external service dependency inside the repo; Hermes or another agent runtime is the main external integration point.
12. The main architecture diagram should therefore show three layers.
First, the external agent runtime loads the system prompt and skills. Second, the skills govern operator interaction and phase-specific reasoning. Third, the checkpoint utilities persist and recover session state in SQLite, creating a feedback loop from runtime output back into long-lived engagement memory.
Main entry points: sentinel_soul_v1.3.md Soul v1.3 · state/SKILL.md State · recon/SKILL.md Recon · exploit/SKILL.md Exploit
Components 21
Runtime boundary
External LLM host that loads the agent prompt package
- Agent runtime · External LLM host such as Hermes that executes the prompt package
Prompt assets
System prompt and supporting operator guidance
- Soul v1.3 · Active 6-layer system prompt that acts as the agent's control plane
sentinel_soul_v1.3.md - Prompt history · Earlier sentinel_soul versions that show prompt evolution
sentinel_soul_v1.0.md
Skills
Operational prompt modules for the engagement lifecycle
- Plan · Initial engagement framing and task decomposition
skills/plan/SKILL.md - Recon · Target discovery and shared session-state schema source
skills/recon/SKILL.md - Enum · Enumeration and structure discovery
skills/enum/SKILL.md - Exploit · Controlled exploitation workflow
skills/exploit/SKILL.md - Post · Post-exploitation actions and follow-on steps
skills/post/SKILL.md - Report · Findings synthesis and reporting
skills/report/SKILL.md - Analyze · Cross-cutting reasoning and interpretation
skills/analyze/SKILL.md - State · Shared session-state contract and coordination surface
skills/state/SKILL.md - Handoff · Transfer of context between operators or stages
skills/handoff/SKILL.md - RT-LLM · Runtime-facing LLM interaction helper
skills/rt-llm/SKILL.md - Checkpoint · Text checkpoint boundary between the agent and persistence
skills/checkpoint/SKILL.md
Persistence
Checkpoint parsing and SQLite-backed session memory
- Checkpoint text · Structured plain-text block emitted by the agent and parsed by persistence tools
- Checkpoint scripts · Utilities that initialize, write, and recover session state
skills/checkpoint/scripts - Init DB · Initializes the SQLite schema
skills/checkpoint/scripts/init_db.py - Write checkpoint · Parses checkpoint blocks and writes session state
skills/checkpoint/scripts/checkpoint.py - Recover state · Reconstructs the latest session state into a checkpoint block
skills/checkpoint/scripts/recover.py - Session DB · Durable session memory backing the checkpoint workflow
Operator layer
Human-facing workflow conventions and notes
- Operator guide · Human workflow and wiki/Obsidian conventions
operator-guide.md
Connections 37
- Agent runtime → Soul v1.3: loads · The external agent runtime loads the active system prompt
- Agent runtime → Prompt history: references · Historical prompt versions document evolution, not runtime behavior
- Agent runtime → Operator guide: consults · Operators use the guide alongside the runtime workflow
- Soul v1.3 → Plan: governs · The system prompt defines how skills are selected and executed
- Soul v1.3 → Recon: governs · The system prompt governs recon behavior and state setup
- Soul v1.3 → Enum: governs · The system prompt governs enumeration behavior
- Soul v1.3 → Exploit: governs · The system prompt governs exploitation behavior
- Soul v1.3 → Post: governs · The system prompt governs post-exploitation behavior
- Soul v1.3 → Report: governs · The system prompt governs reporting behavior
- Soul v1.3 → Analyze: governs · The system prompt governs cross-cutting analysis
- Soul v1.3 → State: governs · The system prompt governs shared session-state handling
- Soul v1.3 → Handoff: governs · The system prompt governs context handoff behavior
- Soul v1.3 → RT-LLM: governs · The system prompt governs runtime-facing LLM interaction
- Soul v1.3 → Checkpoint: governs · The system prompt governs checkpoint emission and recovery
- Plan → Recon: leads to · Planning typically precedes target recon
- Recon → Enum: feeds · Recon findings inform enumeration
- Enum → Exploit: feeds · Enumeration results inform exploitation choices
- Exploit → Post: feeds · Successful exploitation leads into post-exploitation
- Post → Report: feeds · Post-exploitation findings are summarized in reporting
- Analyze → Recon: supports · Analysis can be used at any stage, especially during recon
- Analyze → Exploit: supports · Analysis can inform exploitation decisions
- State → Recon: defines · Recon defines the shared session-state schema
- State → Enum: shared by · Enumeration reads and extends the shared state
- State → Exploit: shared by · Exploitation reads and extends the shared state
- State → Post: shared by · Post-exploitation reads and extends the shared state
- State → Report: shared by · Reporting consumes the shared state and findings
- State → Handoff: shared by · Handoffs preserve the same session contract
- State → Checkpoint: shared by · Checkpointing persists the shared session contract
- Checkpoint → Checkpoint text: emits · The agent emits a structured plain-text checkpoint block
- Checkpoint text → Write checkpoint: parsed by · The checkpoint utility parses the text contract
- Write checkpoint → Checkpoint scripts: belongs to · Checkpoint writer is part of the scripts boundary
- Checkpoint scripts → Init DB: contains · Schema initialization utility
- Checkpoint scripts → Recover state: contains · State recovery utility
- Write checkpoint → Session DB: writes · Parsed state is persisted in SQLite
- Init DB → Session DB: initializes · Creates or prepares the SQLite session store
- Recover state → Session DB: reads · Recovery pulls the latest session state from SQLite
- Session DB → Checkpoint text: restores as · Persisted state can be reconstructed into checkpoint text