Metadata-Version: 2.5
Name: reware-lighthouse
Version: 0.1.1
Summary: Lighthouse developer CLI — link a repo to a project, enhance prompts, and scan commits
Project-URL: Homepage, https://lighthouse.rewarelabs.com
Author: RewareLabs
License-Expression: LicenseRef-Proprietary
License-File: LICENSE
Keywords: ai-agents,claude-code,code-scanning,codex,mcp,pre-commit,security
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Requires-Dist: httpx<1,>=0.28
Requires-Dist: mcp<3,>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio<2,>=0.25; extra == 'dev'
Requires-Dist: pytest<10,>=8.3; extra == 'dev'
Requires-Dist: respx<1,>=0.22; extra == 'dev'
Requires-Dist: ruff<1,>=0.12; extra == 'dev'
Description-Content-Type: text/markdown

# reware-lighthouse

`reware-lighthouse` connects your Git repository to [Lighthouse](https://lighthouse.rewarelabs.com), so your coding agent gets security guidance for your codebase and every commit is scanned before it lands.

It works with Claude Code and Codex on macOS, Linux, and Windows, and needs Python 3.11 or newer. On Windows, the pre-commit hook runs through [Git for Windows](https://gitforwindows.org).

## Quickstart

```bash
$ uv tool install reware-lighthouse    # or: pipx install reware-lighthouse
$ reware-lighthouse login              # paste the API key from your dashboard
$ cd your-repo
$ reware-lighthouse init
$ reware-lighthouse status
```

Restart your coding agent afterward so it picks up the new skill and MCP server.

What just happened?

1. `login` verified your API key and saved it to `~/.config/lighthouse/config.env`.
2. `init` linked the repository to its Lighthouse project, installed a pre-commit hook, and added the agent skill.
3. `status` checked that your account, project link, and tooling all work.

You'll need an API key first. Create one on the Lighthouse dashboard. It's shown once, so copy it right away.

## Enhance a coding request

Enhancement adds your repository's security rules to a request before your agent starts coding. It only runs when you ask for it, so ordinary requests are never changed.

In Claude Code:

```text
/lighthouse-enhance add a password reset endpoint
```

In Codex, invoke the `lighthouse-enhance` skill with the same request.

Your agent tells you which branch's rules it used, plus any warnings, such as a branch that has no repository-specific rules yet. If enhancement fails, the agent stops and asks before continuing without it. Every enhancement appears in your dashboard history.

To pick a branch, start the request with `--branch`:

```text
/lighthouse-enhance --branch release add a password reset endpoint
```

Without the flag, Lighthouse uses the branch attached to your checkout, then the project's default branch.

## Scan commits

The pre-commit hook runs `reware-lighthouse scan` on your staged changes. Whether a finding blocks the commit depends on the blocking policy saved for your project.

If the API is unreachable or the scan times out, the commit goes through. To change the timeout, set `LIGHTHOUSE_SCAN_TIMEOUT` to a number of seconds.

Lighthouse scanning complements code review and your other security testing; it doesn't replace them.

## What `init` creates

| Path | Purpose |
| --- | --- |
| `~/.config/lighthouse/config.env` (mode `0600`) | Your API key, written by `login`. Never inside a repository. |
| `.lighthouse/project.toml` | The link to your project (`owner/name`). It holds no secret. `init` adds `.lighthouse/` to `.gitignore` so it stays on your machine. |
| `.git/hooks/pre-commit` | A marked block that runs the scan. If a hook already exists, the block is appended. |
| `.mcp.json`, `.codex/config.toml` | The MCP server entry that runs `reware-lighthouse mcp`. |
| `.claude/skills/lighthouse-enhance/`, `.agents/skills/lighthouse-enhance/` | The enhance skill, set to run only when you invoke it. |

Use `--agent`, `--no-hook`, or `--no-mcp` to set up less. If a step can't finish, `init` reports which items were created, which were already in place, and which need you. Rerunning it is safe.

Note that `init` never edits shared hook setups. If Git uses a shared or global hooks directory (`core.hooksPath` pointing outside the repository), or you use the pre-commit framework, add `reware-lighthouse scan` to that hook yourself. Edits you make to files `init` created are preserved.

## Commands

| Command | What it does |
| --- | --- |
| `login` | Saves and verifies your API key. Accepts `--api-key`, `--api-base`, and `--yes` to skip prompts. |
| `logout` | Removes the saved key. A key set in the environment stays active. |
| `init` | Links the repository and sets up the hook, MCP config, and skill. |
| `deinit` | Removes what `init` created here, as long as you haven't edited it. Your key and scan reports stay. |
| `status` | Checks your account, project link, and tooling. Exits nonzero if something's wrong. |
| `scan` | Scans staged changes. Accepts `--project`, `--repo`, and `--branch`. The hook runs it for you. |
| `mcp` | Runs the MCP server over stdio. Your agent starts it, so you rarely run it by hand. |

Run any command with `--help` for an example.

## Environment variables

| Variable | Meaning |
| --- | --- |
| `LIGHTHOUSE_API_KEY` | Your API key. It works without `login`, and `logout` doesn't remove it. |
| `LIGHTHOUSE_API_BASE_URL` | Use a different Lighthouse API endpoint. |
| `LIGHTHOUSE_PROJECT` | Use this project instead of the link file or Git remote. |
| `LIGHTHOUSE_SCAN_TIMEOUT` | Scan timeout in seconds. |

## What leaves your machine

- **Enhancement** sends the request you give the skill, plus the repository and branch. Lighthouse stores the original and enhanced prompts and shows them in your dashboard history.
- **Pre-commit scans** send your staged diff (deleted files included), plus your branch, your `HEAD` commit, the newest commit already on the remote and how many commits you haven't pushed, so the server can review the change against the matching code.

## Update

```bash
$ uv tool upgrade reware-lighthouse    # or: pipx upgrade reware-lighthouse
```

If the API needs a newer version, commands tell you to upgrade and show the commands above.

## Uninstall

Clean up before you remove the tool. Once it's gone, nothing is left to run `deinit` or `logout`.

```bash
$ reware-lighthouse deinit             # in each repository you set up
$ reware-lighthouse logout
$ uv tool uninstall reware-lighthouse  # or: pipx uninstall reware-lighthouse
```

`logout` only removes the key from your machine. To revoke it, ask an admin to rotate or delete it on the dashboard.

## License

Proprietary. See `LICENSE`.
