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.htmlindex 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 makingco-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.jsonindex 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.tsindex 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();