# Scout OSS
Scout OSS is a local web research agent and mission-driven intelligence scanner.
It searches multiple sources, follows promising leads, and writes structured markdown briefs. Use it for open-source discovery, trend monitoring, opportunity scouting, builder research, and technical signal tracking.
## Video demo
[](media/scout-oss-quickstart.mp4)
- inline preview: `media/scout-oss-quickstart-preview.gif`
- full video: `media/scout-oss-quickstart.mp4`
## Why Scout
- local-first: run it from your machine, keep your workflow in files
- markdown-first: every run ends as a readable brief, not a chat log
- mission-driven: tell it what to hunt, not just what to answer
- multi-source: combine Hacker News, GitHub, Jina Reader, and more as adapters are added
- skill-friendly: use it directly from CLI or as an OpenCode skill
## Best use cases
- find open-source AI tools worth tracking
- monitor technical trends and product launches
- scout grants, fellowships, hackathons, and programs
- discover builders publishing interesting work in public
- generate recurring research briefs for a niche
## What works today
- autonomous run planning
- exploration loop with tool calls
- markdown brief generation
- local memory file for dedupe across runs
- working adapters: Hacker News, GitHub, Jina Reader
## Current limitations
- many adapters are still being ported: `exa`, `reddit`, `youtube`, `tavily`, `gemini`, `linkedin`, `lobsters`, `x`
- GitHub trending is approximated through the GitHub Search API
- right now the strongest experience is technical signal scanning with the working adapters
## Install
```bash
git clone https://github.com/lout33/scout-oss.git scout-oss
cd scout-oss
pip install -r requirements.txt
cp .env.example .env
```
If you already downloaded or copied the folder, start here:
```bash
cd scout-oss
pip install -r requirements.txt
cp .env.example .env
```
Then edit `.env` and set the backend you want.
## Model backends
Scout supports three backend paths:
- `gpt-*` models through Codex auth
- Anthropic models through `ANTHROPIC_API_KEY`
- Bedrock-hosted Anthropic models through `AWS_BEARER_TOKEN_BEDROCK`
Examples:
- `SCOUT_MODEL=gpt-5.4`
- `SCOUT_MODEL=claude-sonnet-4-6`
- `SCOUT_MODEL=claude-haiku-4-5-20251001`
- `SCOUT_MODEL=sonnet`
- `SCOUT_MODEL=haiku`
Selection logic:
- if the model starts with `gpt-` and Codex auth exists, Scout uses Codex
- else if `AWS_BEARER_TOKEN_BEDROCK` is set, Scout uses Bedrock
- else if `ANTHROPIC_API_KEY` is set, Scout uses Anthropic directly
Minimum useful setup:
- `SCOUT_MODEL=gpt-5.4`
- `codex login --device-auth`
Optional env vars:
- `ANTHROPIC_API_KEY`
- `AWS_BEARER_TOKEN_BEDROCK`
- `JINA_API_KEY`
- `GITHUB_TOKEN`
- `SCOUT_OUTPUT_DIR`
- `SCOUT_CONTEXT_DIR`
- `SCOUT_MEMORY_FILE`
- `SCOUT_LOOP_INTERVAL_MINUTES`
## Quickstart
Run a direct scan:
```bash
python agent.py --mission "Find 3 interesting technical signals from today" --tokens 5000
```
Cheap helper:
```bash
./quick.sh --mission "Find 2 interesting GitHub repos from this week"
```
Standard wrapper:
```bash
./scout.sh --tokens 20000 --mission "Find open-source agent tooling worth tracking"
```
Three parallel scans:
```bash
./daily.sh --tokens 10000
```
Loop mode:
```bash
./scout.sh --tokens 10000 --interval 60 --loop --mission "Track daily technical signals"
```
## Example missions
- `Find 3 interesting technical signals from the last 48 hours`
- `Find open-source AI tooling shipped this week`
- `Find grants, fellowships, or programs with real deadlines`
- `Find builders publishing concrete experiments in public`
- `Find AI developer tools with real traction on GitHub and Hacker News`
## OpenCode skill usage
Scout can also run as an OpenCode skill.
Expected layout:
```text
scout-oss/
SKILL.md
agent.py
scout.sh
quick.sh
daily.sh
adapters/
```
Then use the skill entrypoint or run the commands directly from the repo folder.
## Output
By default Scout writes markdown briefs to:
- `./inbox/`
Sample output shape:
- `examples/sample-brief.md`
- quick video walkthrough: `media/scout-oss-quickstart.mp4`
## Working adapters
- `adapters/hn/scripts/hn.py`
- `adapters/github/scripts/githunt.py`
- `adapters/jina/scripts/jina_read.py`
## Repo map
- `agent.py` - core scout engine
- `scout.sh` - standard wrapper
- `quick.sh` - cheap helper
- `daily.sh` - three parallel missions
- `templates/missions/` - reusable mission prompts
- `examples/sample-brief.md` - sample output shape
- `SKILL.md` - OpenCode skill entry
## First-run smoke test
This should work after setup:
```bash
python agent.py --mission "Use hn_front, github_trending, and jina_read to find 2 interesting technical signals from today and write a brief." --tokens 2500
```
If setup is correct, Scout writes a markdown brief to `inbox/`.
## Positioning
Scout OSS is for people who want a local research agent, not just an LLM chat window. If you care about research automation, open-source discovery, technical trend monitoring, or markdown-first agent workflows, this repo is for you.