You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs: restyle README to match the CodeBoarding repo
Match the engine repo's README formatting: plain title + tagline + intro, a
`·`-separated links line, language badges, sentence-case section headers,
period-terminated bullets, lighter bold, and no emoji legend (drop the centered
logo block). Content is unchanged — formatting only.
Review system design on every pull request, not just the diff.
5
4
6
-
Visual system-design review for pull requests. CodeBoarding analyzes the architecture before and after a change, then comments on the PR with an inline Mermaid diagram showing what changed.
7
-
</div>
5
+
CodeBoarding analyzes your architecture before and after a change, then comments on the PR with an inline Mermaid diagram of what changed — added, modified, and deleted components and the relationships between them. It runs the [CodeBoarding](https://github.com/CodeBoarding/CodeBoarding) engine in CI: static analysis combined with LLM reasoning.
- Builds or reuses a baseline architecture analysis for the PR base.
12
21
- Runs incremental analysis on the PR head, then diffs components and relationships.
13
-
- Posts a sticky PR comment with an inline Mermaid map — 🟩 added · 🟨 modified · 🟥 deleted (dashed), for both nodes and edges.
22
+
- Posts a sticky PR comment with an inline Mermaid map. Green is added, yellow is modified, red (dashed) is deleted, for both nodes and edges.
14
23
15
24
A PR comment looks like this:
16
25
@@ -31,7 +40,7 @@ graph LR
31
40
linkStyle 1 stroke:#1f883d,stroke-width:2px;
32
41
```
33
42
34
-
## Usage
43
+
## Quick start
35
44
36
45
Create `.github/workflows/codeboarding.yml`:
37
46
@@ -40,7 +49,7 @@ name: CodeBoarding review
40
49
41
50
on:
42
51
pull_request:
43
-
# Generate ONCE, when the PR becomes reviewable — not on every push, so you
52
+
# Generate once, when the PR becomes reviewable, not on every push, so you
44
53
# don't spend an LLM job per commit. Use [opened] for strictly creation-only,
45
54
# or add `synchronize` to re-run on each push. Refresh anytime with /codeboarding.
46
55
types: [opened, reopened, ready_for_review]
@@ -70,15 +79,15 @@ jobs:
70
79
llm_api_key: ${{ secrets.OPENROUTER_API_KEY }}
71
80
```
72
81
73
-
Add the API key as a repository secret (**Settings → Secrets and variables → Actions**):
82
+
Add the API key as a repository secret (Settings → Secrets and variables → Actions):
74
83
75
84
```text
76
85
OPENROUTER_API_KEY = sk-or-...
77
86
```
78
87
79
-
That's the only required setup — it's passed via `llm_api_key` above. (For local runs with `scripts/run_local.sh`, export `OPENROUTER_API_KEY` as an env var instead.)
88
+
That is the only required setup, passed via `llm_api_key` above. For local runs with `scripts/run_local.sh`, export `OPENROUTER_API_KEY` as an environment variable instead.
80
89
81
-
**Models are optional.** Omit `agent_model`/`parsing_model` to use the engine's default for your provider, or pin them — inline or from a repository **variable** (a model name isn't a secret, so use `vars.`, not `secrets.`):
90
+
Models are optional. Omit `agent_model`and`parsing_model` to use the engine's default for your provider, or pin them inline or from a repository variable (a model name is not a secret, so use `vars.`, not `secrets.`):
82
91
83
92
```yaml
84
93
with:
@@ -87,25 +96,25 @@ That's the only required setup — it's passed via `llm_api_key` above. (For loc
**Model format (OpenRouter):** a bare OpenRouter slug (e.g. `anthropic/claude-sonnet-4`) — exactly one `/`, **no `openrouter/` prefix** (that's the LiteLLM form; the action rejects it early). Other providers use their own native model ids.
99
+
Model format on OpenRouter is a bare slug (e.g. `anthropic/claude-sonnet-4`): exactly one `/`, with no `openrouter/` prefix (that is the LiteLLM form, which the action rejects early). Other providers use their own native model ids.
91
100
92
101
## Bring your own LLM provider
93
102
94
-
OpenRouter is the default, but you can use any provider the engine supports — set `llm_provider` and pass that provider's key:
103
+
OpenRouter is the default, but you can use any provider the engine supports. Set `llm_provider` and pass that provider's key:
95
104
96
105
```yaml
97
106
with:
98
107
llm_provider: anthropic # omit for OpenRouter (default)
99
108
llm_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
100
109
```
101
110
102
-
`llm_provider: <name>` hands your key to the engine as `<NAME>_API_KEY`, and the engine auto-selects that provider. Set **exactly one** key per run.
111
+
`llm_provider: <name>` hands your key to the engine as `<NAME>_API_KEY`, and the engine auto-selects that provider. Set exactly one key per run.
@@ -116,31 +125,31 @@ OpenRouter is the default, but you can use any provider the engine supports —
116
125
| `aws_bedrock` | `AWS_BEARER_TOKEN_BEDROCK` |
117
126
| `ollama` | `OLLAMA_BASE_URL` |
118
127
119
-
This table mirrors the engine and may lag it — the source of truth is the engine's provider registry ([`agents/llm_config.py`](https://github.com/CodeBoarding/CodeBoarding/blob/main/agents/llm_config.py)). Any provider it adds that follows the `<NAME>_API_KEY` convention works here with no action change.
128
+
This table mirrors the engine and may lag it. The source of truth is the engine's provider registry, [`agents/llm_config.py`](https://github.com/CodeBoarding/CodeBoarding/blob/main/agents/llm_config.py). Any provider it adds that follows the `<NAME>_API_KEY` convention works here with no action change.
120
129
121
130
</details>
122
131
123
132
## When it runs
124
133
125
-
- **PR opened / reopened / marked ready** — generated once (per the `on:` triggers above). It does **not** re-run on every push, so you never spend an LLM job per commit; the comment reflects that point until refreshed.
126
-
- **`/codeboarding` comment** — a trusted collaborator (`OWNER`/`MEMBER`/`COLLABORATOR`) regenerates the diagram against the **current** PR head, even if one already exists. It re-runs and updates the same comment in place (the action reacts with 👀). Change the keyword via `trigger_command`.
134
+
- On a PR being opened, reopened, or marked ready for review, the diagram is generated once (per the `on:` triggers above). It does not re-run on every push, so you never spend an LLM job per commit; the comment reflects that point until refreshed.
135
+
- On a `/codeboarding` comment, a trusted collaborator (`OWNER`, `MEMBER`, or `COLLABORATOR`) regenerates the diagram against the current PR head, even if one already exists. It re-runs and updates the same comment in place. Change the keyword via `trigger_command`.
127
136
128
-
The command needs the `issue_comment` trigger and runs from your **default branch** (GitHub's rule), so it only works once the workflow is merged there. On-demand runs on fork PRs are refused, so fork code is never analyzed with your secrets.
137
+
The command needs the `issue_comment` trigger and runs from your default branch (a GitHub rule), so it only works once the workflow is merged there. On-demand runs on fork PRs are refused, so fork code is never analyzed with your secrets.
129
138
130
139
## Inputs
131
140
132
141
| Input | Default | Description |
133
142
|---|---|---|
134
143
| `llm_api_key` | required | Your LLM provider API key (see `llm_provider`). |
135
-
| `llm_provider` | `openrouter` | Provider for the key — mapped to `<NAME>_API_KEY` (e.g. `anthropic`, `openai`, `google`). |
136
-
| `github_token` | `${{ github.token }}` | Token used to post/update the PR comment. |
144
+
| `llm_provider` | `openrouter` | Provider for the key, mapped to `<NAME>_API_KEY` (e.g. `anthropic`, `openai`, `google`). |
145
+
| `github_token` | `${{ github.token }}` | Token used to post or update the PR comment. |
0 commit comments