talent-agent

+#.
+#.
-#######.
.
+#.
+#.
-#######.

Talent Agent CLI

talent-agent

AI-powered talent profile search using natural language. CLI tool with interactive TUI, JSON output, pipe mode, and MCP server.

Installation

Prerequisites

• Bun v1.3+

Install and run

npm install -g talent-agent && talent-agent

This installs the CLI globally and launches the interactive TUI. If Bun is not installed, you will be prompted to install it.

Or run without installing:

npx talent-agent "Find React developers in Lisbon"

Authentication

talent-agent login              # Interactive (choose method)
talent-agent login --email      # Email magic code
talent-agent login --google     # Google OAuth
talent-agent login --wallet     # Wallet (SIWE)
talent-agent whoami             # Check auth status
talent-agent logout             # Clear credentials

Quick Start

# Search for profiles
talent-agent "Find React developers in Lisbon"

# JSON output (auto-enabled when piping stdout)
talent-agent --json "Find senior Python engineers"

# Refine a previous search
talent-agent --session abc123 "Only show those with 5+ years"

# Get detailed profile by index
talent-agent --session abc123 --detail 0

# Interactive TUI (default when no query)
talent-agent

# Pipe mode (JSONL in, JSONL out)
echo '{"action":"search","query":"Find Rust devs"}' | talent-agent --pipe

# MCP server mode
talent-agent --serve

Modes

Single-Shot

Run a query, get results, exit. Pass --json for machine-readable output wrapped in a success/error envelope.

talent-agent "Find full-stack engineers in London"
talent-agent --json "Find ML engineers" | jq '.data.profiles[].displayName'

Interactive TUI

A two-column terminal UI with search history on the left and results on the right.

Tab          Switch focus between sidebar and search input
Up/Down      Navigate search history or results
Enter        Submit search / select history item
d + number   Show detail for profile at that index
n            Next page of results
q / Ctrl+C   Quit

Pipe Mode

Read JSONL from stdin, write JSONL to stdout. Designed for agent-to-agent communication.

# New format (Zod-validated)
echo '{"action":"search","id":"req-1","query":"Find React devs"}' | talent-agent --pipe
echo '{"action":"detail","id":"req-2","session":"abc","index":0}' | talent-agent --pipe

# Legacy format (still supported)
echo '{"query":"Find React devs"}' | talent-agent --pipe

Each response is a JSON envelope with request ID correlation:

{"success":true,"data":{...},"meta":{"durationMs":3200,"tokensUsed":1847,"toolsCalled":["searchProfiles"]},"id":"req-1"}

MCP Server

Expose talent-agent as a Model Context Protocol server over stdio, making it natively usable by Claude, Cursor, Gemini CLI, GitHub Copilot, and other MCP-compatible clients.

talent-agent --serve

Tools exposed: talent_search, talent_detail, talent_refine.

Options

Flag	Short	Description
--help	-h	Show help message
--version	-v	Show version number
--json	-j	Output results as JSON envelope
--session <id>	-s	Continue a previous search session
--detail <index>	-d	Show detailed profile at index from last search
--pipe	-p	JSONL mode: read from stdin, write to stdout
--debug	-D	Print agent diagnostics to stderr
--serve		Start as MCP server (stdio transport)

Combine --help and --json to get a structured capabilities schema for agent self-discovery:

talent-agent --help --json

Sessions

Sessions maintain conversation history for multi-turn refinement.

# Initial search
RESULT=$(talent-agent --json "Find Python developers")
SESSION=$(echo "$RESULT" | jq -r '.data.session')

# Refine
talent-agent --json --session "$SESSION" "Only show those in Lisbon"

# Detail
talent-agent --json --session "$SESSION" --detail 0

Agent Mode

JSON Envelope

All --json and --pipe output uses a standardized envelope:

Success:

{
  "success": true,
  "data": {"type": "search", "session": "abc", "profiles": [...]},
  "meta": {"durationMs": 3200, "tokensUsed": 1847, "toolsCalled": ["searchProfiles"]}
}

Error:

{
  "success": false,
  "error": "Rate limit hit. Wait 60s and retry, or use a different API key.",
  "code": "RATE_LIMIT"
}

Debug Mode

Add --debug to see agent internals on stderr (does not pollute JSON on stdout):

talent-agent --debug --json "Find React devs" 2>debug.log

[debug] Agent calling: searchProfiles
[debug] Tool input: {"languages":["React"],"location":"Lisbon"}
[debug] Tool response: 142ms, 23 profiles
[debug] Agent total: 1,847 tokens, 3.2s

Structured Exit Codes

Code	Meaning
0	Success
1	Application error (no results, agent failure)
2	Invalid arguments or usage
3	Missing or invalid API keys
4	Rate limit, timeout, transient failure

Error Codes

Code	Meaning
CONNECTION_ERROR	Service unreachable
AUTH_ERROR	Invalid API key
RATE_LIMIT	Rate limit exceeded
CONTEXT_OVERFLOW	Session too long
VALIDATION_ERROR	Invalid input
SESSION_NOT_FOUND	Session does not exist
INDEX_OUT_OF_RANGE	Profile index out of bounds
UNKNOWN_ERROR	Unclassified error

Programmatic API

Import talent-agent as a library in your TypeScript/JavaScript project:

npm install talent-agent

import { TalentSearch } from "talent-agent";

const ts = new TalentSearch();

// Search
const { result, meta } = await ts.search("Find React developers in Lisbon");
console.log(result.profiles);

// Refine
const refined = await ts.refine(result.session, "Only seniors");

// Detail
const detail = await ts.detail(result.session, 0);

MCP Server Integration

Cursor

Add to your Cursor MCP settings (.cursor/mcp.json):

{
  "mcpServers": {
    "talent-agent": {
      "command": "bunx",
      "args": ["talent-agent", "--serve"]
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "talent-agent": {
      "command": "bunx",
      "args": ["talent-agent", "--serve"]
    }
  }
}

Docker

Run the MCP server in a container:

docker build -f docker/Dockerfile -t talent-agent .
docker compose -f docker/docker-compose.yml up talent-agent-mcp

Environment Variables

Variable	Required	Description
TALENT_PRO_URL	No	Talent Pro app URL (default: https://pro.talent.app)
TALENT_CLI_SESSION	No	Default session ID
NO_COLOR	No	Disable ANSI color output

Development

git clone https://github.com/talentprotocol/talent-agent.git
cd talent-agent
bun install

bun run start                    # Run the CLI
bun run start -- "Find devs"    # Single-shot
bun run dev                      # Watch mode
bun run test                     # Run tests
bun run test:watch               # Run tests in watch mode
bun run typecheck                # Type checking
bun run format                   # Format code
bun run format:check             # Check formatting

Changeset Workflow

This project uses Changesets for versioning and publishing.

bun run changeset               # Create a changeset
bun run version:packages        # Apply changesets to bump versions

Architecture

src/
  index.ts              CLI entry point, argument parser, mode router
  agent.ts              Agent wrapper: sessions, query(), getDetail()
  errors.ts             AI-friendly error rewriting + structured exit codes
  format.ts             Terminal formatters (ANSI) for human-readable output
  env.ts                Environment variable loading and validation
  lib.ts                Programmatic TS/JS API (TalentSearch class)
  auth/                 Authentication (email, Google, wallet)
  programmatic/
    single-shot.ts      Single-shot mode
    piped.ts            Pipe mode (JSONL)
  tui/
    app.ts              TUI layout and keyboard handling
    results.ts          Results panel
    sidebar.ts          Search history sidebar
  mcp/
    server.ts           MCP server (talent_search, talent_detail, talent_refine)

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

1. Fork the repository
2. Create a feature branch (git checkout -b my-feature)
3. Make your changes and add tests
4. Run bun run typecheck && bun run format:check && bun run test to verify
5. Create a changeset (bun run changeset) describing your change
6. Open a pull request

License

Apache-2.0