# companion-inc/alpha-hub architecture

> Architecture diagram of the GitHub repository companion-inc/alpha-hub, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/companion-inc/alpha-hub
- Repository: https://github.com/companion-inc/alpha-hub

## Overview

Alpha Hub is a research-agent CLI and library for searching papers, retrieving reports, asking paper questions, reading associated repositories, and keeping local annotations. Its main workflow starts with a CLI command, dispatches to alphaXiv-backed operations, and presents results; paper retrieval also reads saved notes. Login provides alphaXiv access, while annotations persist locally. A stdio MCP server exposes related tools to agents, and the library API offers programmatic access. The documented features are represented, but unsampled command and server implementation details are not inferred beyond indexed references and README statements.

Main entry points: [`cli/src/lib/alphaxiv.js`](https://github.com/companion-inc/alpha-hub/blob/main/cli/src/lib/alphaxiv.js) (alphaXiv client), [`cli/src/index.js`](https://github.com/companion-inc/alpha-hub/blob/main/cli/src/index.js) (CLI dispatcher), [`cli/src/commands/get.js`](https://github.com/companion-inc/alpha-hub/blob/main/cli/src/commands/get.js) (Paper retrieval), [`cli/src/lib/output.js`](https://github.com/companion-inc/alpha-hub/blob/main/cli/src/lib/output.js) (Output formatting)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI commands"]
  node_cli_entry["CLI dispatcher<br/>[index.js]"]
  node_search_cmd["Paper search<br/>[search.js]"]
  node_get_cmd["Paper retrieval<br/>[get.js]"]
  node_ask_cmd["Paper Q&amp;A<br/>[ask.js]"]
  node_code_cmd["Repository reading<br/>[code.js]"]
  node_annotate_cmd["Annotation commands<br/>[annotate.js]"]
  node_login_cmd["Login and status<br/>[login.js]"]
  node_formatting["Output formatting<br/>[output.js]"]
end

subgraph group_research["Paper research"]
  node_alphaxiv["alphaXiv client<br/>[alphaxiv.js]"]
  node_papers["Paper ID helpers<br/>[papers.js]"]
end

subgraph group_state["Local state"]
  node_annotations[("Annotation storage<br/>[annotations.js]")]
end

subgraph group_identity["Authentication"]
  node_auth["OAuth and tokens<br/>[auth.js]"]
  node_auth_store[("Auth token file<br/>[auth.js]")]
end

subgraph group_integration["Agent integrations"]
  node_library_api["Library API<br/>[index.js]"]
  node_mcp_server["MCP server<br/>[server.js]"]
  node_mcp_tools["MCP tools<br/>[tools.js]"]
end

node_user(("Research agent"))
node_alpha_service["alphaXiv services"]
node_mcp_client(("MCP agent"))

node_user -->|"runs commands"| node_cli_entry
node_cli_entry -->|"registers"| node_search_cmd
node_cli_entry -->|"registers"| node_get_cmd
node_cli_entry -->|"registers"| node_ask_cmd
node_cli_entry -->|"registers"| node_code_cmd
node_cli_entry -->|"registers"| node_annotate_cmd
node_cli_entry -->|"registers"| node_login_cmd
node_search_cmd -->|"searches papers"| node_alphaxiv
node_search_cmd -->|"formats results"| node_formatting
node_get_cmd -->|"normalizes IDs"| node_papers
node_get_cmd -->|"fetches report"| node_alphaxiv
node_get_cmd -->|"reads note"| node_annotations
node_get_cmd -->|"formats result"| node_formatting
node_ask_cmd -->|"asks question"| node_alphaxiv
node_ask_cmd -->|"formats answer"| node_formatting
node_code_cmd -->|"reads repository"| node_alphaxiv
node_code_cmd -->|"formats result"| node_formatting
node_annotate_cmd -->|"normalizes IDs"| node_papers
node_annotate_cmd -->|"reads and writes"| node_annotations
node_annotate_cmd -->|"formats output"| node_formatting
node_login_cmd -->|"manages session"| node_auth
node_alphaxiv -->|"gets valid token"| node_auth
node_alphaxiv -->|"calls MCP and REST"| node_alpha_service
node_auth -->|"reads and writes"| node_auth_store
node_auth -->|"OAuth and verifies"| node_alpha_service
node_library_api -->|"calls paper operations"| node_alphaxiv
node_library_api -->|"manages notes"| node_annotations
node_library_api -->|"normalizes papers"| node_papers
node_mcp_client -->|"uses stdio tools"| node_mcp_server
node_mcp_server -->|"dispatches tools"| node_mcp_tools
node_mcp_tools -->|"runs paper operations"| node_alphaxiv
node_mcp_tools -->|"manages notes"| node_annotations
node_mcp_tools -->|"normalizes IDs"| node_papers

click node_cli_entry "https://github.com/companion-inc/alpha-hub/blob/main/cli/src/index.js"
click node_search_cmd "https://github.com/companion-inc/alpha-hub/blob/main/cli/src/commands/search.js"
click node_get_cmd "https://github.com/companion-inc/alpha-hub/blob/main/cli/src/commands/get.js"
click node_ask_cmd "https://github.com/companion-inc/alpha-hub/blob/main/cli/src/commands/ask.js"
click node_code_cmd "https://github.com/companion-inc/alpha-hub/blob/main/cli/src/commands/code.js"
click node_annotate_cmd "https://github.com/companion-inc/alpha-hub/blob/main/cli/src/commands/annotate.js"
click node_login_cmd "https://github.com/companion-inc/alpha-hub/blob/main/cli/src/commands/login.js"
click node_formatting "https://github.com/companion-inc/alpha-hub/blob/main/cli/src/lib/output.js"
click node_alphaxiv "https://github.com/companion-inc/alpha-hub/blob/main/cli/src/lib/alphaxiv.js"
click node_papers "https://github.com/companion-inc/alpha-hub/blob/main/cli/src/lib/papers.js"
click node_annotations "https://github.com/companion-inc/alpha-hub/blob/main/cli/src/lib/annotations.js"
click node_auth "https://github.com/companion-inc/alpha-hub/blob/main/cli/src/lib/auth.js"
click node_auth_store "https://github.com/companion-inc/alpha-hub/blob/main/cli/src/lib/auth.js"
click node_library_api "https://github.com/companion-inc/alpha-hub/blob/main/cli/src/lib/index.js"
click node_mcp_server "https://github.com/companion-inc/alpha-hub/blob/main/cli/src/mcp/server.js"
click node_mcp_tools "https://github.com/companion-inc/alpha-hub/blob/main/cli/src/mcp/tools.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli_entry,node_search_cmd,node_get_cmd,node_ask_cmd,node_code_cmd,node_annotate_cmd,node_login_cmd,node_formatting toneBlue
class node_alphaxiv,node_papers toneAmber
class node_annotations toneMint
class node_auth,node_auth_store toneRose
class node_library_api,node_mcp_server,node_mcp_tools,node_user,node_alpha_service,node_mcp_client toneIndigo
```

## Components

### CLI commands

- [CLI dispatcher](https://github.com/companion-inc/alpha-hub/blob/main/cli/src/index.js): `cli/src/index.js`
- [Paper search](https://github.com/companion-inc/alpha-hub/blob/main/cli/src/commands/search.js): `cli/src/commands/search.js`
- [Paper retrieval](https://github.com/companion-inc/alpha-hub/blob/main/cli/src/commands/get.js): `cli/src/commands/get.js`
- [Paper Q&A](https://github.com/companion-inc/alpha-hub/blob/main/cli/src/commands/ask.js): `cli/src/commands/ask.js`
- [Repository reading](https://github.com/companion-inc/alpha-hub/blob/main/cli/src/commands/code.js): `cli/src/commands/code.js`
- [Annotation commands](https://github.com/companion-inc/alpha-hub/blob/main/cli/src/commands/annotate.js): `cli/src/commands/annotate.js`
- [Login and status](https://github.com/companion-inc/alpha-hub/blob/main/cli/src/commands/login.js): `cli/src/commands/login.js`
- [Output formatting](https://github.com/companion-inc/alpha-hub/blob/main/cli/src/lib/output.js): `cli/src/lib/output.js`

### Paper research

- [alphaXiv client](https://github.com/companion-inc/alpha-hub/blob/main/cli/src/lib/alphaxiv.js): `cli/src/lib/alphaxiv.js`
- [Paper ID helpers](https://github.com/companion-inc/alpha-hub/blob/main/cli/src/lib/papers.js): `cli/src/lib/papers.js`

### Local state

- [Annotation storage](https://github.com/companion-inc/alpha-hub/blob/main/cli/src/lib/annotations.js): `cli/src/lib/annotations.js`

### Authentication

- [OAuth and tokens](https://github.com/companion-inc/alpha-hub/blob/main/cli/src/lib/auth.js): `cli/src/lib/auth.js`
- [Auth token file](https://github.com/companion-inc/alpha-hub/blob/main/cli/src/lib/auth.js): `cli/src/lib/auth.js`

### Agent integrations

- [Library API](https://github.com/companion-inc/alpha-hub/blob/main/cli/src/lib/index.js): `cli/src/lib/index.js`
- [MCP server](https://github.com/companion-inc/alpha-hub/blob/main/cli/src/mcp/server.js): `cli/src/mcp/server.js`
- [MCP tools](https://github.com/companion-inc/alpha-hub/blob/main/cli/src/mcp/tools.js): `cli/src/mcp/tools.js`

### Other components

- **Research agent**
- **alphaXiv services**
- **MCP agent**

## Connections

- Research agent → CLI dispatcher: runs commands (evidence: `README.md`)
- CLI dispatcher → Paper search: registers (evidence: `cli/src/index.js`)
- CLI dispatcher → Paper retrieval: registers (evidence: `cli/src/index.js`)
- CLI dispatcher → Paper Q&A: registers (evidence: `cli/src/index.js`)
- CLI dispatcher → Repository reading: registers (evidence: `cli/src/index.js`)
- CLI dispatcher → Annotation commands: registers (evidence: `cli/src/index.js`)
- CLI dispatcher → Login and status: registers (evidence: `cli/src/index.js`)
- Paper search → alphaXiv client: searches papers (evidence: `cli/src/commands/search.js`)
- Paper search → Output formatting: formats results (evidence: `cli/src/commands/search.js`)
- Paper retrieval → Paper ID helpers: normalizes IDs (evidence: `cli/src/commands/get.js`)
- Paper retrieval → alphaXiv client: fetches report (evidence: `cli/src/commands/get.js`)
- Paper retrieval → Annotation storage: reads note (evidence: `cli/src/commands/get.js`)
- Paper retrieval → Output formatting: formats result (evidence: `cli/src/commands/get.js`)
- Paper Q&A → alphaXiv client: asks question (evidence: `cli/src/commands/ask.js`)
- Paper Q&A → Output formatting: formats answer (evidence: `cli/src/commands/ask.js`)
- Repository reading → alphaXiv client: reads repository (evidence: `cli/src/commands/code.js`)
- Repository reading → Output formatting: formats result (evidence: `cli/src/commands/code.js`)
- Annotation commands → Paper ID helpers: normalizes IDs (evidence: `cli/src/commands/annotate.js`)
- Annotation commands → Annotation storage: reads and writes (evidence: `cli/src/commands/annotate.js`)
- Annotation commands → Output formatting: formats output (evidence: `cli/src/commands/annotate.js`)
- Login and status → OAuth and tokens: manages session (evidence: `cli/src/commands/login.js`)
- alphaXiv client → OAuth and tokens: gets valid token (evidence: `cli/src/lib/alphaxiv.js`)
- alphaXiv client → alphaXiv services: calls MCP and REST (evidence: `cli/src/lib/alphaxiv.js`)
- OAuth and tokens → Auth token file: reads and writes (evidence: `cli/src/lib/auth.js`)
- OAuth and tokens → alphaXiv services: OAuth and verifies (evidence: `cli/src/lib/auth.js`)
- Library API → alphaXiv client: calls paper operations (evidence: `cli/src/lib/index.js`)
- Library API → Annotation storage: manages notes (evidence: `cli/src/lib/index.js`)
- Library API → Paper ID helpers: normalizes papers (evidence: `cli/src/lib/index.js`)
- MCP agent → MCP server: uses stdio tools (evidence: `README.md`)
- MCP server → MCP tools: dispatches tools (evidence: `cli/src/mcp/server.js`)
- MCP tools → alphaXiv client: runs paper operations (evidence: `cli/src/mcp/tools.js`)
- MCP tools → Annotation storage: manages notes (evidence: `cli/src/mcp/tools.js`)
- MCP tools → Paper ID helpers: normalizes IDs (evidence: `cli/src/mcp/tools.js`)