paceflow 0.2.0

Local-first CLI that turns AI coding session history and git metadata into engineering analytics.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195

# `paceflow` Install Notes

`paceflow` is a single-file CLI binary. Download the archive for your platform, extract it, and run:

```bash
paceflow --help
paceflow ingest
```

## Install with Cargo

If you have the Rust toolchain (or `cargo-binstall`) on your machine, this is the fastest path.

### `cargo binstall` (prebuilt binary, no compilation)

```bash
cargo binstall paceflow
paceflow --help
```

`cargo binstall` downloads the matching prebuilt release artifact for your target triple and drops `paceflow` in `~/.cargo/bin`. No Rust compilation required. Install `cargo-binstall` itself with `cargo install cargo-binstall` or grab its prebuilt binary from [cargo-bins/cargo-binstall](https://github.com/cargo-bins/cargo-binstall#installation).

### `cargo install` (compiles from source)

```bash
cargo install --locked paceflow
paceflow --help
```

Builds from crates.io with your local toolchain. Slower than `binstall` (rusqlite-bundled + reqwest + tokio take a few minutes), but works on any target where Rust compiles. If install fails, try `rustup update` first.

Both commands install to `~/.cargo/bin/paceflow`, which rustup adds to `PATH` by default. See [Add `paceflow` To `PATH`](#add-paceflow-to-path) if it isn't.

## Prebuilt Releases

Download a release from [GitHub Releases](https://github.com/PaceFlow/ai-engineering-analytics/releases).

Supported release targets:

| Platform | Asset |
| --- | --- |
| Windows x86_64 | `paceflow-x86_64-pc-windows-msvc.zip` |
| Linux x86_64 (glibc) | `paceflow-x86_64-unknown-linux-gnu.tar.gz` |
| macOS Apple Silicon | `paceflow-aarch64-apple-darwin.tar.gz` |

Windows PowerShell example:

```powershell
$version = "v0.2.0"
$asset = "paceflow-x86_64-pc-windows-msvc.zip"
Invoke-WebRequest `
  -Uri "https://github.com/PaceFlow/ai-engineering-analytics/releases/download/$version/$asset" `
  -OutFile $asset
Expand-Archive .\$asset -DestinationPath .\paceflow
.\paceflow\paceflow.exe --help
```

macOS/Linux example:

```bash
version="v0.2.0"
asset="paceflow-x86_64-unknown-linux-gnu.tar.gz"
curl -L "https://github.com/PaceFlow/ai-engineering-analytics/releases/download/${version}/${asset}" -o "${asset}"
tar -xzf "${asset}"
./paceflow-x86_64-unknown-linux-gnu/paceflow --help
```

For macOS Apple Silicon, use `paceflow-aarch64-apple-darwin.tar.gz` as the asset name.

## Add `paceflow` To `PATH`

Git hooks and team setup scripts call `paceflow` by name, so the binary must be available on `PATH`.

macOS/Linux, for a downloaded release:

```bash
mkdir -p ~/.local/bin
cp ./paceflow-x86_64-unknown-linux-gnu/paceflow ~/.local/bin/paceflow
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
exec zsh
paceflow --help
```

For macOS Apple Silicon, replace `paceflow-x86_64-unknown-linux-gnu` with `paceflow-aarch64-apple-darwin`. If you use Bash, append the `PATH` line to `~/.bashrc` instead of `~/.zshrc`.

macOS/Linux, for a local development build:

```bash
cargo install --path .
paceflow --help
paceflow --version           # paceflow 0.2.0 (<git-sha> clean, <commit-time>)
```

This builds in release mode and copies the binary to `~/.cargo/bin/paceflow`, which is on `PATH` by default for rustup installs. Re-run the command (add `--force` after the first time) to pick up changes. `paceflow --version` embeds the git commit SHA and a `clean`/`dirty` flag from `build.rs`, so you can confirm which checkout you're running:

```bash
paceflow --version                          # what's on PATH
git rev-parse --short=12 origin/main        # what main currently points at
git fetch origin main && git diff --stat HEAD origin/main   # check if you're behind main
```

If the SHA in `paceflow --version` matches `git rev-parse --short=12 origin/main` and shows `clean`, you're running an exact build of `origin/main`.

If `~/.cargo/bin` is not on `PATH`, add it:

```bash
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.zshrc
exec zsh
```

Windows PowerShell, for a local development build:

```powershell
cargo install --path .
paceflow --help
paceflow --version           # paceflow 0.2.0 (<git-sha> clean, <commit-time>)
```

This installs `paceflow.exe` to `%USERPROFILE%\.cargo\bin\`, which rustup adds to the user `Path`. Re-run with `--force` after the first install to pick up changes. `paceflow --version` embeds the git commit SHA and a `clean`/`dirty` flag from `build.rs`, so you can confirm which checkout you're running:

```powershell
paceflow --version                          # what's on PATH
git rev-parse --short=12 origin/main        # what main currently points at
git fetch origin main; git diff --stat HEAD origin/main   # check if you're behind main
(Get-Command paceflow).Source               # which paceflow.exe resolves on PATH
```

If the SHA in `paceflow --version` matches `git rev-parse --short=12 origin/main` and shows `clean`, you're running an exact build of `origin/main`.

If `cargo install` reports the binary is not on `PATH`, add `%USERPROFILE%\.cargo\bin` for the current user and open a new PowerShell window:

```powershell
[Environment]::SetEnvironmentVariable(
  "Path",
  [Environment]::GetEnvironmentVariable("Path", "User") + ";$env:USERPROFILE\.cargo\bin",
  "User"
)
```

Windows PowerShell, for a downloaded release:

```powershell
$installDir = "$env:USERPROFILE\bin\paceflow"
New-Item -ItemType Directory -Force -Path $installDir | Out-Null
Copy-Item .\paceflow\paceflow.exe $installDir
[Environment]::SetEnvironmentVariable(
  "Path",
  [Environment]::GetEnvironmentVariable("Path", "User") + ";$installDir",
  "User"
)
```

Open a new PowerShell window, then verify:

```powershell
paceflow --help
```

## Build From Source

```bash
git clone https://github.com/PaceFlow/ai-engineering-analytics.git
cd ai-engineering-analytics
cargo install --path . --force
```

## macOS Gatekeeper

If Gatekeeper blocks `paceflow`, go to `System Settings > Privacy & Security` and click `Open Anyway`, then rerun the binary.

Fresh extractions can inherit quarantine from the downloaded archive. If needed, clear quarantine on the extracted folder:

```bash
xattr -dr com.apple.quarantine paceflow-aarch64-apple-darwin
./paceflow-aarch64-apple-darwin/paceflow --help
```

## Requirements

- Git must be installed and available on `PATH`
- `paceflow` reads local Claude Code sessions from `~/.claude/projects/*/*.jsonl`
- `paceflow` reads local Codex sessions from `~/.codex/sessions`
- `paceflow` reads local Cursor state/history from the OS config directory under `Cursor/User`
- `paceflow` reads local OpenCode history from `~/.local/share/opencode/opencode.db` and `~/.local/share/opencode/storage/session_diff`
- GitHub PR sync requires `paceflow github token` or `PACEFLOW_GITHUB_TOKEN`

## Optional Overrides

- `PACEFLOW_HOME` changes the base directory for Paceflow's local analytics state
- `PACEFLOW_CURSOR_STATE_PATH` points to a custom Cursor `state.vscdb`
- `PACEFLOW_CURSOR_HISTORY_PATH` points to a custom Cursor history directory
- `PACEFLOW_OPENCODE_DB_PATH` points to a custom OpenCode database
- `PACEFLOW_GITHUB_TOKEN` overrides the saved GitHub token for PR sync

Local analytics state lives under `~/.paceflow/paceflow.db` by default. The source assistant and git data remains in its original location.