Vorepo Agents Framework

Build autonomous AI trading agents for GitHub repository momentum. MIT · Paper-mode only · Python 3.10+

---

$ vorepo-agents top --limit 8

MICMARKI   2153     stars/24h  microsoft/markitdown
HARMONEY   2111     stars/24h  harry0703/MoneyPrinterTurbo
LUMUNDER   1512     stars/24h  Lum1104/Understand-Anything
CODBUILD   1125     stars/24h  codecrafters-io/build-your-own-x
COLCODEG   1108     stars/24h  colbymchenry/codegraph
NOUHERME   1050     stars/24h  NousResearch/hermes-agent
AFFEVERY   1011     stars/24h  affaan-m/everything-claude-code
MULANDRE    941     stars/24h  multica-ai/andrej-karpathy-skills

Live output from the public Vorepo API. Updated continuously.

---

Why this exists

When a GitHub repo gets hot — stars accelerating, contributors joining, real product traction landing — its mindshare moves before any market reflects it. vorepo-agents lets you:

• See momentum the moment it shifts. Live star velocity, contributor growth, news mentions, all in one signal.
• Stress-test your strategy over N runs against the live market in paper mode (real signals, simulated execution). Historical replay is on the roadmap.
• Add qualitative LLM context on top of the quantitative signal. Feed Trending + Hacker News + Reddit news into RAG and let the model weigh the news against the velocity numbers.
• Write your own strategy in ~50 lines by subclassing one base class.

Built as a thin client on the public Vorepo API. Adapted from Polymarket/agents (MIT). Same clean modular architecture, re-pointed at GitHub momentum instead of prediction markets. The on-chain stack was removed; Vorepo settles via a simple REST API.

---

Quickstart (2 minutes)

git clone https://github.com/Vorepo-com/vorepo-agents.git
cd vorepo-agents
python3 -m venv venv && source venv/bin/activate
pip install -e .

# list tradeable repos
vorepo-agents repos --limit 10

# top repos by 24h star velocity (the momentum signal)
vorepo-agents top --limit 10

# run a strategy in PAPER mode ($100 virtual)
vorepo-agents run --strategy momentum --balance 100 --top-n 5 --per-trade 10
# strategies: momentum | dip_buy | mean_reversion

# multi-run benchmark (N runs vs the live market, aggregated stats — not a historical replay)
vorepo-agents backtest --strategy momentum --runs 5

Sample agent.run_once() output:

{
  "strategy": "momentum",
  "actions_executed": 5,
  "portfolio": {
    "starting_balance": 100.0,
    "portfolio_value": 99.53,
    "pnl_pct": -0.47,
    "trades": 5
  }
}

Sample backtest output (5 runs aggregated):

{
  "strategy": "momentum",
  "runs": 5,
  "avg_pnl_pct": -0.31,
  "best_pnl_pct": 0.42,
  "worst_pnl_pct": -0.89,
  "stdev": 0.51
}

---

Use cases

• Dev researchers quantifying "is this repo hot" hypothesis-free, with reproducible numbers.
• Maintainers monitoring competitors and key dependencies for velocity inflection points.
• Indie hackers paper-trading hunches on developer-trend cycles before they go mainstream.
• AI engineers wiring repo-momentum signals into LLM pipelines and agent loops.
• Educators teaching trading-system design and backtesting without real-money risk.

---

How it works

vorepo_agents/
  client.py              # VorepoClient — public Vorepo API (read)
  trader.py              # PaperTrader — simulated execution, virtual balance
  objects.py             # pydantic models (Repo, Quote, TradeResult)
  strategies/
    base.py              # Strategy interface (subclass + implement decide())
    momentum.py          # buy top-N by star velocity
    dip_buy.py           # buy dips that still have velocity
    mean_reversion.py    # buy oversold-vs-24h with healthy velocity
  connectors/
    news.py              # GitHub Trending + Hacker News + Reddit
  application/
    agent.py             # the autonomous decision loop
  backtest.py            # run a strategy N× vs live market, aggregate
  cli.py                 # command-line interface

Full architecture notes: docs/architecture.md.

---

Write your own strategy

from vorepo_agents.strategies.base import Strategy, Action

class MyStrategy(Strategy):
    name = "my_strategy"

    def decide(self) -> list[Action]:
        repos = self.client.get_repos(category="ai-ml", limit=50)
        picks = [r for r in repos if (r.star_velocity_24h or 0) > 100]
        return [
            Action(side="buy", ticker=r.ticker, usdc_amount=10.0,
                   reason=f"{r.full_repo_name} hot")
            for r in picks[:3]
        ]

Then run it via the Agent:

from vorepo_agents.application.agent import Agent
from vorepo_agents.trader import PaperTrader

agent = Agent(strategy=MyStrategy(), trader=PaperTrader(starting_balance=100))
print(agent.run_once())

---

LLM-powered strategies (optional)

pip install -r requirements-llm.txt

Then feed GitHub Trending + Hacker News + Reddit news through Chroma RAG into an LLM to add qualitative context on top of the quantitative velocity signal. Worked examples in docs/llm_strategy.md.

---

Why paper-only

This framework ships paper-trading only. No wallet keys, no real money, no live order endpoint. Wiring it to a funded account is intentionally left to you, and is subject to Vorepo's Terms of Service.

We follow (and go further than) the Polymarket/agents safety pattern: their live order is commented out behind a ToS notice. Ours simply isn't shipped.

---

What this framework does NOT contain

By design, this is a client for the public Vorepo API. It does not contain, and cannot reveal, Vorepo's pricing methodology, internal constants, or platform-side execution logic. Those are proprietary and out of scope. This framework only consumes documented public endpoints.

---

Roadmap

• Historical-replay backtester (deterministic replays of past market data, beyond the live-market multi-run aggregation already shipping).
• More signal connectors: Lobsters, dev.to trending, npm / PyPI / crates.io download velocity, package-manager-level signals.
• Strategy plugin system — load custom strategies from PyPI packages.
• Notebook-friendly API for Jupyter exploration.

Open an issue or thumbs-up an existing one. Community drives priorities.

---

Contributing

PRs welcome. Fork, branch, tests, PR. See CONTRIBUTING.md. Good first issues:

• New strategies (category-rotation, LLM-scored, time-of-day).
• New signal connectors (Lobsters, dev.to, package managers).
• Backtesting harness improvements.
• Edge-case test coverage.

---

License

MIT. See LICENSE and NOTICE for the Polymarket attribution.

---

Stay in the loop

The Vorepo platform that powers this framework is pre-launch. Early access and new-strategy announcements go to vorepo.com/waitlist.html first.

---

Vorepo Agents Framework is an independent open-source project. Not financial advice. Trading involves risk; this framework ships in simulation mode for education and research.