🔌 Project 4: GitHub and documents
An agent that only chats is useful; an agent that reads your sources and it’s powerful. In this project, you connect Hermes to your code (GitHub) and your documents, then ask questions about the repo and files—all running on the local model, in Vault mode, without anything proprietary leaving your machine.
🎯 Goal: connect your sources
In the previous project, you gave the agent a memory and a face. Now you’ll give it eyes: access to your code on GitHub and your local documents. The difference is huge — instead of answering only with what it "knows" from training, the agent starts answering about your repo and your own files. And since it runs locally in Vault, neither proprietary code nor documents leave your machine.
📋 What you’ll deliver
- •A GitHub repository connected to the agent.
- •A folder/file of documents that the agent can read.
- •At least one question answered one about the repo and another about the doc.
- •Confirmation that everything ran in Vault, without leaks.
Prerequisites: the Hermes agent already connected to the local model (Project 2 / module 3.2). This project’s connections are made through Hermes interface (connections panel) — there's no CLI command to "connect GitHub," so we describe the action in the UI. For diagnostics, you can use the actual commands hermes status e hermes doctor.
Key concepts
A bridge from the agent to an external source (repo, folder).
The code or document the agent will read.
Airgapped mode: nothing leaves the machine.
The log that shows which sources the agent accessed.
🐙 Step 1 — Connect GitHub
The first source is the GitHub. In Hermes’ connections dashboard, you authorize access to a repository. From then on, the agent can read the files, commit history, and project structure — and answer questions about it without you opening each file by hand.
Open the connections panel
In the Hermes dashboard, go to the connections/integrations and choose "GitHub".
Authorize access
Follow the authorization flow on the screen and select only the repos that you want to expose to the agent.
Confirm the connection
The repo now appears as connected. That’s the sign that the agent can see it.
✓ Best practices
- ✓Connect only the repos you need—minimum scope.
- ✓Start with a small repo to test the workflow.
- ✓Review in Activity what the agent read the first time.
- ✓Keep the local model selected before asking.
✗ Avoid
- ✗Give access to your entire account “because you're too lazy” to filter.
- ✗Connect and send it to the cloud right away—confirm Vault mode first.
- ✗Assume it connected without checking the connection status.
- ✗Forgetting to disconnect repos you no longer use.
🔎 How to verify this step
The repo appears as connected in the panel. If the connection doesn’t come up, run hermes status e hermes doctor in the terminal to diagnose the agent’s status before trying again.
Key concepts
Where you connect GitHub and other sources.
The step that grants the agent read permission.
Grant only what’s needed, repo by repo.
Real agent diagnostic commands.
📄 Step 2 — Read documents
The second source is your documents: PDFs, notes, spreadsheets, contracts, manuals. Instead of connecting to a remote service, you point the agent to a local folder or file. It reads the content directly from disk — and, precisely because it's local, not a single byte of the document needs to go online.
New here? "Read a document" here means the agent extracts text from the file and uses it as context for its response. Large documents use up the context window (remember Modules 1.4 / 2.4): that’s why the agent model has 64k, so the document, question, and answer all fit without running out of space.
Select the folder/file
In the Hermes interface, select the documents folder or attach the file you want the agent to read.
Let the agent index/read
It processes the content locally. A larger document takes longer to read the first time.
See it logged in Activity
Document access appears in the log—confirm it was the right file.
🔎 How to verify this step
Ask for a one-line summary of the document. If the summary matches the file's actual content (and isn't something generic), the agent really read the local source.
Key concepts
Folder/file on your disk, read without a network connection.
Process the content so you can refer to it later.
The file’s text goes into the context window.
A large context can fit a document + question + answer.
🔎 Step 3 — Ask about the repo and the doc
With connected sources, the agent becomes a a copilot that knows your material. Instead of hunting for the information, you ask — and it answers by pulling from the actual repo and documents. That's when connectivity becomes valuable.
O GitHub and the documents go into the agent local, which answers questions about your material. All within the dashed Vault border — nothing crosses over to the internet. That boundary is what makes it safe to connect proprietary sources.
💬 Questions worth asking
- •"Summarize the latest commits and what changed in them."
- •"Find the function that does X and explain how it works."
- •"What is this PDF about? List the 3 main points."
- •"Is there an inconsistency between the contract and the specs document?"
🔎 How to verify this step
The response cites specific details from your repo/doc (file name, function, PDF excerpt) that only exist in the connected source. If it's generic, the agent didn't read it—check the connection.
Key concepts
Answers based on your material, not just its training.
The more specific you are, the better grounded the response.
A real detail proves the source was read.
Cross-referencing the repo + doc reveals inconsistencies.
🔒 Step 4 — Keep everything in the Vault
Connecting proprietary sources is safe only if the reading happens 100% local. That's the role of the Vault: the agent uses the Ollama model on your machine and doesn't send anything to the cloud. Before asking about client code or a contract, confirm that Vault mode is on and that the selected model is local.
🛡️ Privacy checklist before asking
- •The mode Vault is active (air-gapped).
- •The model in the lower-right corner is the local (e.g., qwen3-coder-64k).
- •Only the required repos/folders are connected.
- •Activity shows no external calls.
💡 Practical tip
Want definitive proof? Disconnect the network cable / turn off Wi-Fi and ask a question about the repo. If the agent keeps responding, it means the reading and inference are actually running on your machine — exactly what Vault promises.
🔎 How to verify this step
With the network off, the agent still answers questions about the repo and the document. This offline test confirms that no proprietary source material had to leave the machine.
Key concepts
Airgapped mode: 100% local reading and responses.
Confirmed in the bottom-right corner of Hermes.
Code/docs that must not leak — keep them in the Vault.
No network, and it still responds = real privacy.
✅ Step 5 — Result: an agent based on your sources
You’ve gone from an agent that only "knew things about the world" to an agent that knows your code and your documents — and responds about them without anything leaving the machine. This is the kind of use that truly justifies running locally: working with proprietary material that could never go to the cloud.
🏁 Expected result
- ✓GitHub connected and the repo showing as accessible.
- ✓Document read, with a summary that matches the actual content.
- ✓Questions answered with details from your material.
- ✓Everything confirmed in Vault — works even offline.
⚠️ If something doesn’t match
- ✗Generic answer? The agent didn't read the source—check the connection in the panel.
- ✗Connection won’t come up? Run
hermes status/hermes doctor. - ✗Stuck offline? Confirm that the selected model is local, not in the cloud.
Optional self-check: Why is connecting GitHub and documents to local Hermes safe for proprietary data?
🎯 Project summary
Next module:
3.5 — Project 5: Background agents 24/7 at $0