First Light gives coding agents a compact, read-only briefing before they work in an unfamiliar repository.
It reports:
- repository identity and Git branch
- applicable
AGENTS.md,CLAUDE.md, andGEMINI.mdfiles - project shape and likely entry points
- declared build and test commands
- the current change surface
- a ranked, bounded “read first” list
The script uses only the Python standard library, never runs detected build commands, and does not modify the repository it inspects.
- Python 3.11+
- Git is optional; non-Git directories still receive a useful briefing
python skill/first-light/scripts/first_light.py /path/to/repositoryClone this repository, then copy skill/first-light into either or both personal skill directories:
| Agent | Destination |
|---|---|
| Codex | ~/.codex/skills/first-light |
| Claude Code | ~/.claude/skills/first-light |
Start a new agent session after installation. The skill triggers automatically when entering an unfamiliar repository, or it can be invoked explicitly as first-light//first-light where supported.
They solve different problems and work well together.
| First Light | Codex /init |
|
|---|---|---|
| Output | Disposable repository briefing | Persistent AGENTS.md scaffold |
| Writes files | No | Yes |
| Best time to use | At the start of unfamiliar or resumed work | When a repository needs durable agent guidance |
| Main value | Fast situational awareness | Team conventions that load in future sessions |
Use First Light to understand what is present now. Use /init, then edit the resulting AGENTS.md, to preserve stable build commands, conventions, constraints, and verification expectations.
python -m unittest discover -s tests -vMIT