Skip to content

Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.

docs: add GitHub Companion documentation, star button on docs page

Salman Qureshi54f95d7a0d36
diff --git a/docs/docs.html b/docs/docs.html
index b303747b..9ad9f387 100644
--- a/docs/docs.html
+++ b/docs/docs.html
@@ -220,6 +220,50 @@
width: 100%;
}
}
+
+ .github-btn {
+ display: inline-flex;
+ align-items: center;
+ gap: 6px;
+ background: rgba(255,255,255,0.06);
+ border: 1px solid var(--border);
+ color: var(--gray) !important;
+ padding: 4px 12px 4px 10px;
+ border-radius: 6px;
+ font-size: 0.85em;
+ font-weight: 500;
+ text-decoration: none !important;
+ transition: all 0.2s;
+ }
+
+ .github-btn:hover {
+ border-color: #444;
+ color: var(--white) !important;
+ background: rgba(255,255,255,0.1);
+ }
+
+ .github-btn svg {
+ flex-shrink: 0;
+ }
+
+ .github-btn-text {
+ font-size: 0.95em;
+ font-weight: 600;
+ }
+
+ .github-btn-count {
+ display: inline-flex;
+ align-items: center;
+ background: rgba(255,255,255,0.06);
+ border-left: 1px solid var(--border);
+ margin-left: 2px;
+ margin-right: -6px;
+ padding: 3px 8px;
+ border-radius: 0 5px 5px 0;
+ font-weight: 600;
+ min-width: 20px;
+ text-align: center;
+ }
</style>
</head>
@@ -230,8 +274,11 @@
<div class="nav-links" id="navLinks">
<a href="index.html">Home</a>
<a href="docs.html" style="color: var(--cyan);">Docs</a>
- <a href="https://github.com/cosmicstack-labs/mercury-agent" class="nav-cta" target="_blank"
- rel="noopener">GitHub</a>
+ <a href="https://github.com/cosmicstack-labs/mercury-agent" class="github-btn" target="_blank" rel="noopener">
+ <svg viewBox="0 0 16 16" width="16" height="16" fill="currentColor" style="vertical-align:-2px;"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg>
+ <span class="github-btn-text">Star</span>
+ <span class="github-btn-count" id="ghStars"></span>
+ </a>
</div>
<button class="nav-toggle" id="navToggle" aria-label="Menu">☰</button>
</div>
@@ -252,6 +299,8 @@
<a href="#daemon">Background Mode</a>
<a href="#service">System Service</a>
<a href="#platform-guide">Platform Guide</a>
+ <div class="sidebar-heading">Integrations</div>
+ <a href="#github-companion">GitHub Companion</a>
<div class="sidebar-heading">Reference</div>
<a href="#tools">Built-in Tools</a>
<a href="#configuration">Configuration</a>
@@ -640,6 +689,115 @@
</div>
</div>
+ <h2 id="github-companion">GitHub Companion</h2>
+ <p>Mercury can act as your GitHub companion — creating pull requests, reviewing PRs, managing issues, and making
+ co-authored commits — all through natural conversation. When configured, five GitHub tools are registered
+ alongside Mercury's built-in toolset, letting you manage repositories without leaving the terminal.</p>
+
+ <div class="callout">
+ <div class="callout-title">Conditional availability</div>
+ <p>GitHub tools <strong>only appear when <code>GITHUB_TOKEN</code> is configured</strong> via
+ <code>mercury doctor</code>. Without a token, these tools are not registered and won't be available in
+ conversation.</p>
+ </div>
+
+ <h3>Setup</h3>
+ <p>Run <code>mercury doctor</code> and fill in the three GitHub fields:</p>
+ <div class="terminal-inline">
+ <code>mercury doctor</code>
+ </div>
+ <ul>
+ <li><strong>GitHub username</strong> — your GitHub username (used for commit attribution)</li>
+ <li><strong>GitHub email</strong> — the email tied to your GitHub account</li>
+ <li><strong>GitHub PAT</strong> — a fine-grained Personal Access Token with repo scope</li>
+ </ul>
+ <p>Press <strong>Enter</strong> on any field to keep its current value. When the PAT is set, you'll see:</p>
+ <div class="terminal-inline">
+ <code>✓ GitHub tools registered (5)</code>
+ </div>
+
+ <h3>Creating a Fine-Grained PAT</h3>
+ <ol>
+ <li>Go to <a href="https://github.com/settings/personal-access-tokens/new" target="_blank"
+ rel="noopener">github.com/settings/personal-access-tokens/new</a></li>
+ <li>Give it a name (e.g. <code>mercury-agent</code>) and set an expiration</li>
+ <li>Under <strong>Repository access</strong>, select <strong>All repositories</strong> or choose specific
+ repos</li>
+ <li>Under <strong>Permissions → Repository permissions</strong>, grant:
+ <ul>
+ <li><strong>Contents</strong> — Read and write (for commits)</li>
+ <li><strong>Pull requests</strong> — Read and write</li>
+ <li><strong>Issues</strong> — Read and write</li>
+ </ul>
+ </li>
+ <li>Click <strong>Generate token</strong> and copy it immediately</li>
+ </ol>
+
+ <h3>GitHub Tools</h3>
+ <table class="cmd-table">
+ <thead>
+ <tr>
+ <th>Tool</th>
+ <th>What it does</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>create_pr</td>
+ <td>Create a pull request with title, body, head branch, and base branch</td>
+ </tr>
+ <tr>
+ <td>review_pr</td>
+ <td>Fetch a PR diff, review the changes, and post review comments</td>
+ </tr>
+ <tr>
+ <td>list_issues</td>
+ <td>List and filter issues in a repository (open, closed, by label, by assignee)</td>
+ </tr>
+ <tr>
+ <td>create_issue</td>
+ <td>Create a new issue with title, body, labels, and assignees</td>
+ </tr>
+ <tr>
+ <td>github_api</td>
+ <td>Raw GitHub API access — an escape hatch for any endpoint not covered above</td>
+ </tr>
+ </tbody>
+ </table>
+
+ <h3>Co-Authored Commits</h3>
+ <p>When Mercury commits code using <code>git_commit</code>, it automatically appends a
+ <code>Co-authored-by: Mercury &lt;[email protected]&gt;</code> trailer. This means Mercury's avatar
+ appears alongside yours in GitHub's commit history — giving credit where it's due.</p>
+
+ <h3>Example: Create a PR</h3>
+ <div class="terminal-window" style="max-width: 680px; margin: 20px 0;">
+ <div class="terminal-bar">
+ <span class="terminal-dot red"></span>
+ <span class="terminal-dot yellow"></span>
+ <span class="terminal-dot green"></span>
+ <span class="terminal-title">mercury</span>
+ </div>
+ <div class="terminal-body" style="min-height: auto; padding: 16px 24px;">
+ <p style="margin:0;color:var(--gray);">You: <span style="color:var(--white);">create a PR for this change</span></p>
+ <p style="margin:0;color:var(--gray-dim); font-style:italic;"> [Using: git_status, git_diff, git_log]</p>
+ <p style="margin:0;color:var(--gray-dim); font-style:italic;"> [Using: create_pr]</p>
+ <p style="margin:0;color:var(--green);"> PR #42 created: "Add GitHub Companion docs section"</p>
+ <p style="margin:0;color:var(--cyan);">Mercury:</p>
+ <p style="margin:0;color:var(--white);"> Done! I've created PR #42 — "Add GitHub Companion docs section"</p>
+ <p style="margin:0;color:var(--gray);"> targeting <code>main</code> from <code>feature/github-companion-docs</code>.</p>
+ <p style="margin:0;color:var(--gray);"> The PR includes the new section, sidebar link, and nav button update.</p>
+ </div>
+ </div>
+
+ <h3>Security</h3>
+ <div class="callout" style="border-left-color: var(--yellow);">
+ <div class="callout-title" style="color: var(--yellow);">PAT storage</div>
+ <p>Your GitHub PAT is stored in <code>~/.mercury/mercury.yaml</code> alongside your other configuration. It is
+ never sent to any external service — only to the GitHub API directly from your machine. Treat this file like
+ any other credential: don't commit it, don't share it, and rotate the token if you suspect it's compromised.</p>
+ </div>
+
<h2 id="tools">Built-in Tools</h2>
<p>Mercury has 21 built-in tools it can use during conversations. These are not CLI commands — the agent decides
when to call them.</p>
@@ -958,6 +1116,17 @@
sidebarLinks.forEach(l => l.classList.remove('active'));
if (current) current.link.classList.add('active');
}, { passive: true });
+
+ fetch('https://api.github.com/repos/cosmicstack-labs/mercury-agent')
+ .then(function (r) { return r.json(); })
+ .then(function (data) {
+ var el = document.getElementById('ghStars');
+ if (el && data.stargazers_count != null) {
+ var n = data.stargazers_count;
+ el.textContent = n >= 1000 ? (n / 1000).toFixed(1).replace(/\.0$/, '') + 'k' : n;
+ }
+ })
+ .catch(function () {});
</script>
</body>