Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions .github/skills/testing/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
---
name: testing
description: Guide for testing TUI (terminal user interface) applications. Use this when asked to verify code changes.
---

# Testing

This skill helps you create and run tests for terminal user interface (TUI) applications.

## When to use this skill

Use this skill when you need to:
- Verify that code changes work as intended
- Ensure existing functionality as specified in `maind.md` and `README.md` is not broken

## Starting the application

- Run `scripts/run` where the user would normally run `github-brain`
- `scripts/run pull` equivalently runs `github-brain pull`
- `scripts/run mcp` equivalently runs `github-brain mcp`
- Ensure `.env` files is configured to use the `github-brain-test` organization
- Use GitHub MCP to add new issue/PRs/discussions as needed for testing
- Simulate user input: Send key presses, control combinations, or specific commands to the running application.
- Capture and analyze screen output: The testing tool captures the terminal display (or buffer) at specific moments in time.
- Make assertions: Verify that the screen content matches the expected output (e.g., checking if specific text is present at certain coordinates or if the cursor position is correct).
4 changes: 4 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
- The app is coded in Markdown file `main.md` and compiled to Go code using the instructions in `.github/prompts/compile.prompt.md`.
- When prompted to make changes, start by updating `main.md` and letting me to review the changes before compiling again.
- Everything must fit into a single `main.md` / `main.go` file pair. Avoid creating new files.
- `README.md` contains usage instructions. Read it to understand how the app should work.
72 changes: 13 additions & 59 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,19 +31,17 @@ Or use `npx github-brain` to run without installing globally.
## Usage

```sh
github-brain <command> [<args>]
github-brain
```

**Workflow:**
Launches the interactive TUI where you can:

1. Use `login` to authenticate with GitHub (or set `GITHUB_TOKEN` manually)
2. Use `pull` to populate the local database
3. Use `mcp` to start the MCP server
1. **Login** - Authenticate with GitHub
2. **Pull** - Populate the local database with GitHub data

Re-run `pull` anytime to update the database with new GitHub data.
Re-run pull anytime to update the database with new GitHub data.

Each command has its own arguments. Some can be set via environment variables. The app will also load environment variables from a `.env` file in the GitHub Brain's home directory - `~/.github-brain` by default.
You can change the home directory with the `-m` argument available for all commands.
The app loads environment variables from a `.env` file in the GitHub Brain's home directory - `~/.github-brain` by default.

<details>
<summary>Example .env file</summary>
Expand All @@ -53,42 +51,10 @@ You can change the home directory with the `-m` argument available for all comma

</details>

### `login`

Opens your browser to authorize _GitHub Brain_ app and stores resulting `GITHUB_TOKEN` in the `.env` file.
Optionally, you can also specify `ORGANIZATION` to store in the same file.

Example:

```sh
github-brain login
```

| Argument | Description |
| :------- | :----------------------------------------- |
| `-m` | Home directory. Default: `~/.github-brain` |

### `pull`

Populate the local database with GitHub data.

Example:

```sh
github-brain pull -o my-org
```

The first run may take a while. Subsequent runs are faster, fetching only new data.

| Argument | Variable | Description |
| :------- | :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------- |
| | `GITHUB_TOKEN` | Your GitHub token. Use `login` command or create a [personal token](https://github.com/settings/personal-access-tokens). **Required.** |
| `-o` | `ORGANIZATION` | The GitHub organization to pull data from. **Required.** |
| `-m` | | Home directory. Default: `~/.github-brain` |
| `-i` | | Pull only selected entities: `repositories`, `discussions`, `issues`, `pull-requests` (comma-separated). |
| `-f` | | Remove all data before pulling. With `-i`, removes only specified items. |
| `-e` | `EXCLUDED_REPOSITORIES` | Repositories to exclude (comma-separated). Useful for large repos not relevant to your analysis. |

<details>
<summary>Personal access token scopes</summary>

Expand All @@ -100,30 +66,18 @@ The first run may take a while. Subsequent runs are faster, fetching only new da

</details>

### `mcp`

Start the MCP server using the local database.

Example:

```sh
github-brain mcp -o my-org
```

| Argument | Variable | Description |
| :------- | :------------- | :------------------------------------------ |
| `-o` | `ORGANIZATION` | GitHub organization. **Required.** |
| `-m` | | Home directory. Default: `~/.github-brain` |

### Additional Arguments
## MCP Server

**Version:**
Start the MCP server using the local database:

```sh
github-brain --version
github-brain mcp
```

Displays the current version (commit hash and build date).
| Argument | Variable | Description |
| :------- | :------------- | :----------------------------------------- |
| `-o` | `ORGANIZATION` | GitHub organization. **Required.** |
| `-m` | | Home directory. Default: `~/.github-brain` |

## MCP Configuration

Expand Down
Loading