Install Houston

Requirements

Step 1

Clone and set up

git clone https://github.com/vistik/houston.git
cd houston
composer setup

composer setup runs these, in order:

1. 1composer install for the PHP dependencies
2. 2copies .env.example to .env if there is no .env yet
3. 3php artisan key:generate
4. 4php artisan migrate --force to create the tables
5. 5npm install and npm run build for the frontend

Step 2

Connect GitHub

Houston talks to GitHub with one token. Pick one of the two.

$ gh auth login

GITHUB_TOKEN=[your token]

Step 3

Run it

On your laptop

$ composer dev

This runs php artisan dev, which starts, side by side:

• web server php artisan serve
• scheduler php artisan schedule:work
• queue worker php artisan queue:listen
• log tail php artisan pail
• Vite npm run dev

Then open http://localhost:8000. If Laravel Herd already serves the app, its .test address works too.

On a long-running server

Serve the app like any Laravel app, then keep two processes running: a queue worker for the syncs, and the scheduler.

$ php artisan queue:work

For the scheduler, either keep php artisan schedule:work running, or add the usual Laravel cron entry:

* * * * * cd /path/to/Houston && php artisan schedule:run >> /dev/null 2>&1

Step 4

Add repositories

1. 1Open Houston and click Watch repository.
2. 2Enter owner/name, or paste the repository's GitHub URL.

A sync is queued straight away. The first one pulls the lookback window, 180 days by default, and can take a while on busy repositories. It pauses before it runs into GitHub's rate limits and resumes when they reset. Follow it under Settings → Syncs, where you can also change each repository's lookback window.

Want to see it work before pointing it at your own code? Watch a busy public repository such as laravel/framework.

From the command line:

php artisan houston:sync                    # every watched repository
php artisan houston:sync laravel/framework  # one repository
php artisan houston:sync --queue            # dispatch to the queue instead

Step 5

Teams and benchmarks

Step 6

Connect an AI assistant (MCP)

Houston runs a read-only MCP server with three tools (list-repositories, get-velocity-report, list-pull-requests) and a give-feedback prompt.

Locally, over stdio

Point your client at php artisan mcp:start houston. With Claude Code:

$ claude mcp add houston -- php /path/to/Houston/artisan mcp:start houston

Any other client, in its JSON config:

{
  "mcpServers": {
    "houston": {
      "command": "php",
      "args": ["/path/to/Houston/artisan", "mcp:start", "houston"]
    }
  }
}

Over HTTP, with a token

Set HOUSTON_MCP_TOKEN in .env to a long random string, then send it as a bearer token to /mcp:

$ claude mcp add --transport http houston http://localhost:8000/mcp \
    --header "Authorization: Bearer $HOUSTON_MCP_TOKEN"

No token set

404, endpoint off

Wrong or missing

401

Matching token

read-only access

Step 7

Configuration

Everything Houston-specific lives in config/houston.php and can be set from .env. Report defaults (period, grouping and the timezone every report is shown in) and benchmarks are set in the app under Settings.