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.

v0.3.3 — improved GitHub onboarding: URL parsing, detailed setup, PAT instructions

Salman Qureshi31e7e2cf7515
diff --git a/docs/docs.html b/docs/docs.html
index ea673d2f..27032320 100644
--- a/docs/docs.html
+++ b/docs/docs.html
@@ -197,6 +197,14 @@
margin-bottom: 4px;
}
+ .callout-warn {
+ border-left-color: var(--yellow);
+ }
+
+ .callout-warn .callout-title {
+ color: var(--yellow);
+ }
+
@media (max-width: 900px) {
.docs-layout {
grid-template-columns: 1fr;
@@ -692,7 +700,7 @@
<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>
+ alongside Mercury's built-in toolset, letting you manage repositories without leaving the terminal or Telegram.</p>
<div class="callout">
<div class="callout-title">Conditional availability</div>
@@ -701,48 +709,83 @@
conversation.</p>
</div>
+ <h3>Why set up GitHub?</h3>
+ <ul>
+ <li><strong>Co-authored commits</strong> — Mercury's avatar appears alongside yours on every commit it helps with</li>
+ <li><strong>Pull requests</strong> — "Create a PR for this change" and Mercury stages, commits, pushes, and opens the PR</li>
+ <li><strong>Issue management</strong> — "Check open issues" or "File a bug for the login crash"</li>
+ <li><strong>Code review</strong> — "Review PR #5" and Mercury reads the diff and posts a summary</li>
+ <li><strong>Full API access</strong> — The <code>github_api</code> tool lets Mercury hit any GitHub endpoint</li>
+ </ul>
+
<h3>Setup</h3>
- <p>Run <code>mercury doctor</code> and fill in the three GitHub fields:</p>
+ <p>Run <code>mercury doctor</code> and fill in the four 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 Personal Access Token with repo scope (fine-grained or classic)</li>
- </ul>
+
+ <h4>1. GitHub username</h4>
+ <p>Your GitHub username. This is used for commit attribution and identifying you in API calls.</p>
+ <div class="terminal-inline">
+ <code>Example: hotheadhacker</code>
+ </div>
+
+ <h4>2. GitHub email (for co-author)</h4>
+ <p>The email that appears in the <code>Co-authored-by</code> trailer on every Mercury-assisted commit. You can use
+ your real email, a GitHub no-reply email (<code>[email protected]</code>), or
+ <code>[email protected]</code> for Mercury's default.</p>
+ <div class="terminal-inline">
+ <code>Example: [email protected]</code>
+ </div>
+
+ <h4>3. GitHub PAT (Personal Access Token)</h4>
+ <p>You need a token so Mercury can authenticate with the GitHub API. <strong>Never share this token.</strong> It's
+ stored locally in <code>~/.mercury/.env</code> and never sent anywhere except GitHub's API.</p>
+
+ <div class="callout callout-warn">
+ <div class="callout-title">Where to create your token</div>
+ <p><strong>Fine-grained PAT (recommended):</strong></p>
+ <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</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>
+ <p><strong>Classic PAT:</strong></p>
+ <ol>
+ <li>Go to <a href="https://github.com/settings/tokens/new" target="_blank"
+ rel="noopener">github.com/settings/tokens/new</a></li>
+ <li>Give it a name (e.g. <code>mercury-agent</code>) and set an expiration</li>
+ <li>Select the <strong>repo</strong> scope (full control of private repositories)</li>
+ <li>Click <strong>Generate token</strong> and copy it immediately</li>
+ </ol>
+ </div>
+
+ <h4>4. Default repo</h4>
+ <p>Set a default repository so you can say <code>"create an issue"</code> without specifying the repo every time.
+ You can enter it in any of these formats:</p>
+ <div class="terminal-inline">
+ <code>hotheadhacker/mercury-agent</code>
+ </div>
+ <div class="terminal-inline">
+ <code>https://github.com/hotheadhacker/mercury-agent</code>
+ </div>
+ <p>Mercury will parse the owner and repo name automatically from either format.</p>
+
<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 PAT</h3>
- <p>Mercury supports both <strong>fine-grained</strong> and <strong>classic</strong> Personal Access Tokens.</p>
- <h4>Option A: Fine-Grained PAT (recommended)</h4>
- <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</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>
- <h4>Option B: Classic PAT</h4>
- <ol>
- <li>Go to <a href="https://github.com/settings/tokens/new" target="_blank"
- rel="noopener">github.com/settings/tokens/new</a></li>
- <li>Give it a name (e.g. <code>mercury-agent</code>) and set an expiration</li>
- <li>Select the <strong>repo</strong> scope (full control of private repositories)</li>
- <li>Click <strong>Generate token</strong> and copy it immediately</li>
- </ol>
-
<h3>GitHub Tools</h3>
<table class="cmd-table">
<thead>
diff --git a/package.json b/package.json
index 52c11ecd..f0ce2039 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "@cosmicstack/mercury-agent",
- "version": "0.3.2",
+ "version": "0.3.3",
"description": "Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI or Telegram.",
"type": "module",
"main": "dist/index.js",
diff --git a/src/index.ts b/src/index.ts
index 46d13c1f..d424b10e 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -90,6 +90,15 @@ function appendToEnv(key: string, value: string): void {
process.env[key] = value;
}
+function parseGithubRepo(input: string): { owner: string; repo: string } | null {
+ const trimmed = input.trim().replace(/\/+$/, '');
+ const urlMatch = trimmed.match(/github\.com\/([^/]+)\/([^/]+)/);
+ if (urlMatch) return { owner: urlMatch[1], repo: urlMatch[2] };
+ const shortMatch = trimmed.match(/^([^/\s]+)\/([^/\s]+)$/);
+ if (shortMatch) return { owner: shortMatch[1], repo: shortMatch[2] };
+ return null;
+}
+
async function configure(existingConfig?: MercuryConfig): Promise<void> {
const isReconfig = !!existingConfig;
const config = existingConfig ?? loadConfig();
@@ -204,33 +213,50 @@ async function configure(existingConfig?: MercuryConfig): Promise<void> {
hr();
console.log('');
- console.log(chalk.bold.white(' GitHub (optional)'));
- console.log(chalk.dim(' Connect Mercury to GitHub for PRs, issues, and co-authored commits.'));
+ console.log(chalk.bold.white(' GitHub Integration (optional)'));
+ console.log(chalk.dim(' Connect Mercury to GitHub so it can create PRs, manage issues,'));
+ console.log(chalk.dim(' review code, and co-author commits on your behalf.'));
console.log(chalk.dim(' Leave empty to skip. You can add it later with mercury doctor.'));
console.log('');
const ghUserCurrent = isReconfig && config.github.username ? ` [${config.github.username}]` : '';
- const ghUsername = await ask(chalk.white(` GitHub username${ghUserCurrent}: `));
+ const ghUsername = await ask(chalk.white(` 1. Your GitHub username${ghUserCurrent}: `));
if (ghUsername) config.github.username = ghUsername;
const ghEmailCurrent = isReconfig && config.github.email ? ` [${config.github.email}]` : '';
- const ghEmail = await ask(chalk.white(` GitHub email${ghEmailCurrent}: `));
+ console.log(chalk.dim(' This appears in the Co-authored-by trailer on commits.'));
+ const ghEmail = await ask(chalk.white(` 2. GitHub email (for co-author)${ghEmailCurrent}: `));
if (ghEmail) config.github.email = ghEmail;
+ console.log('');
+ console.log(chalk.dim(' You need a Personal Access Token (PAT) with repo access.'));
+ console.log(chalk.dim(' Fine-grained (recommended): github.com/settings/personal-access-tokens/new'));
+ console.log(chalk.dim(' → Permissions: Contents (R/W), Pull requests (R/W), Issues (R/W)'));
+ console.log(chalk.dim(' Classic: github.com/settings/tokens/new'));
+ console.log(chalk.dim(' → Scope: repo (full control)'));
const ghTokenCurrent = process.env.GITHUB_TOKEN ? ` [${maskKey(process.env.GITHUB_TOKEN)}]` : '';
- const ghToken = await ask(chalk.white(` GitHub PAT (repo scope)${ghTokenCurrent}: `));
+ const ghToken = await ask(chalk.white(` 3. GitHub PAT${ghTokenCurrent}: `));
if (ghToken) {
appendToEnv('GITHUB_TOKEN', ghToken);
}
if (config.github.username || process.env.GITHUB_TOKEN) {
- const ghOwnerCurrent = isReconfig && config.github.defaultOwner ? ` [${config.github.defaultOwner}]` : '';
- const ghOwner = await ask(chalk.white(` Default GitHub owner/org${ghOwnerCurrent}: `));
- if (ghOwner) config.github.defaultOwner = ghOwner;
-
- const ghRepoCurrent = isReconfig && config.github.defaultRepo ? ` [${config.github.defaultRepo}]` : '';
- const ghRepo = await ask(chalk.white(` Default repo name${ghRepoCurrent}: `));
- if (ghRepo) config.github.defaultRepo = ghRepo;
+ console.log('');
+ console.log(chalk.dim(' Set a default repo so you can say "create an issue" without'));
+ console.log(chalk.dim(' specifying the repo every time. Enter owner/name or a full URL.'));
+ console.log(chalk.dim(' Example: hotheadhacker/mercury-agent'));
+ console.log(chalk.dim(' Example: https://github.com/hotheadhacker/mercury-agent'));
+ const ghOwnerCurrent = isReconfig && config.github.defaultOwner ? ` [${config.github.defaultOwner}/${config.github.defaultRepo}]` : '';
+ const ghRepoInput = await ask(chalk.white(` 4. Default repo${ghOwnerCurrent}: `));
+ if (ghRepoInput) {
+ const parsed = parseGithubRepo(ghRepoInput);
+ if (parsed) {
+ config.github.defaultOwner = parsed.owner;
+ config.github.defaultRepo = parsed.repo;
+ } else {
+ console.log(chalk.yellow(' Could not parse repo. Use format: owner/repo or a GitHub URL.'));
+ }
+ }
}
hr();