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
`agenthint` is a small runtime detection spec, CLI, and library for developer tools that want to know when they are probably being run by an AI agent such as Codex, Claude Code, Cursor, Gemini CLI, or Aider.
13
+
`agenthint` is a small detection spec, CLI, and multi-language library for developer tools that want to know when they are probably being run by an AI agent such as Codex, Claude Code, Cursor, Gemini CLI, Aider, or another automated coding environment.
13
14
14
-
It is built for ergonomics, not security. Use it to choose better output defaults for agents; do not use it as a trust boundary.
15
+
Use it to choose better defaults for agent-driven runs: structured output, quiet logs, no spinners, no pagers, no interactive prompts, and clearer diagnostics.
15
16
16
-
## Why
17
-
18
-
AI agents benefit from different CLI defaults than humans:
19
-
20
-
- structured output instead of decorative output
21
-
- no spinners, pagers, prompts, or browser launches
22
-
- stable section markers and clear exit-code meanings
23
-
- absolute paths and line-oriented diagnostics
24
-
- concise logs that preserve useful debugging context
25
-
26
-
`agenthint` gives CLIs and libraries a shared way to make that decision.
17
+
> Detection is advisory. `agenthint` is for user experience decisions, not authentication, authorization, sandboxing, or policy enforcement.
27
18
28
19
## Quick Start
29
20
21
+
Install the CLI:
22
+
30
23
```sh
31
24
npm install -g agenthint
32
25
# or
33
26
cargo install agenthint
27
+
# or
28
+
python3 -m pip install agenthint
34
29
```
35
30
36
-
```sh
37
-
if agenthint;then
38
-
my-tool --json --no-progress
39
-
else
40
-
my-tool
41
-
fi
42
-
```
43
-
44
-
Use it inside another CLI or script to choose agent-friendly output:
31
+
Use its exit code in scripts:
45
32
46
33
```sh
47
34
if agenthint >/dev/null;then
48
-
exec my-cli --json --no-progress --no-pager "$@"
35
+
exec my-tool --json --no-progress --no-pager "$@"
49
36
else
50
-
exec my-cli"$@"
37
+
exec my-tool"$@"
51
38
fi
52
39
```
53
40
54
-
For agents and wrappers, the preferred explicit convention is `AI_AGENT`:
41
+
Prefer the explicit convention when you control the agent or wrapper:
55
42
56
43
```sh
57
44
AI_AGENT=codex my-tool
58
45
AI_AGENT=claude-code my-tool
59
46
AI_AGENT=my-custom-agent my-tool
60
47
```
61
48
49
+
## Why
50
+
51
+
Humans and agents often need different CLI behavior.
| Friendly summaries | Explicit sections and exit codes |
59
+
60
+
`agenthint` gives tools a shared, explainable way to switch modes without each project inventing its own agent detection logic.
61
+
62
62
## CLI
63
63
64
64
```sh
65
65
agenthint # exit 0 if an agent is likely detected, otherwise 1
66
66
agenthint --json # print the structured detection result
67
-
agenthint --explain # print a short explanation
67
+
agenthint --explain # print a short human-readable explanation
68
68
agenthint doctor # print detection details and setup advice
69
69
agenthint doctor --json
70
-
# print detection details and setup advice as JSON
71
70
agenthint init codex # print the recommended AI_AGENT value
72
71
```
73
72
74
-
Example JSON output:
73
+
Example JSON:
75
74
76
75
```json
77
76
{
@@ -82,47 +81,19 @@ Example JSON output:
82
81
}
83
82
```
84
83
85
-
## Install
86
-
87
-
Install from npm:
88
-
89
-
```sh
90
-
npm install -g agenthint
91
-
agenthint --json
92
-
```
93
-
94
-
Install from crates.io:
84
+
Exit codes:
95
85
96
-
```sh
97
-
cargo install agenthint
98
-
agenthint --json
99
-
```
86
+
| Code | Meaning |
87
+
| --- | --- |
88
+
|`0`| Agent runtime likely detected |
89
+
|`1`| Agent runtime not detected |
90
+
|`2`| Invalid usage or detection error |
100
91
101
-
Install from PyPI:
92
+
Setup-only commands such as `agenthint init <agent>` exit `0`.
102
93
103
-
```sh
104
-
python3 -m pip install agenthint
105
-
agenthint --json
106
-
```
107
-
108
-
Install the latest native binary from GitHub Releases:
109
-
110
-
```sh
111
-
curl -fsSL https://raw.githubusercontent.com/forjd/agenthint/main/install.sh | sh
112
-
```
94
+
## Libraries
113
95
114
-
By default, the install script downloads the latest `agenthint-v*` GitHub Release asset for your platform. Set `AGENTHINT_VERSION` to install a specific release tag.
115
-
116
-
Override the install directory or release version:
117
-
118
-
```sh
119
-
AGENTHINT_INSTALL_DIR=/usr/local/bin sh install.sh
120
-
AGENTHINT_VERSION=agenthint-vX.Y.Z sh install.sh
121
-
```
122
-
123
-
Native binaries are built by GitHub Actions for release assets. The installer verifies `SHA256SUMS` when the selected release provides it.
124
-
125
-
## TypeScript API
96
+
### TypeScript
126
97
127
98
```ts
128
99
import { detectAgent } from"agenthint";
@@ -134,9 +105,7 @@ if (result.isAgent) {
134
105
}
135
106
```
136
107
137
-
## Rust API
138
-
139
-
The repository also contains a Rust implementation under `crates/agenthint`.
108
+
### Rust
140
109
141
110
```rust
142
111
useagenthint::detect_agent;
@@ -148,13 +117,7 @@ if result.is_agent {
148
117
}
149
118
```
150
119
151
-
Run the Rust CLI locally:
152
-
153
-
```sh
154
-
cargo run -q -p agenthint -- --json
155
-
```
156
-
157
-
## Python API
120
+
### Python
158
121
159
122
```python
160
123
from agenthint import detect_agent
@@ -166,124 +129,101 @@ if result.is_agent:
166
129
pass
167
130
```
168
131
169
-
## Detection Model
132
+
## Install
170
133
171
-
The result includes:
134
+
### npm
172
135
173
-
-`isAgent`: whether an agent runtime is likely detected
174
-
-`agent`: known or custom agent name
175
-
-`confidence`: a number from `0` to `1`
176
-
-`signals`: diagnostic signal names, never secret values
136
+
```sh
137
+
npm install -g agenthint
138
+
agenthint --json
139
+
```
177
140
178
-
Detection priority:
141
+
### crates.io
179
142
180
-
1.`AGENTHINT_DISABLE`
181
-
2.`AGENTHINT_FORCE`
182
-
3. explicit `AI_AGENT`
183
-
4. known environment signals
184
-
5. documented filesystem signals
185
-
6. low-confidence parent process signals
186
-
7. low-confidence stdio hints
187
-
188
-
## Supported Agents
189
-
190
-
Current known agent names include:
191
-
192
-
- Codex
193
-
- Claude Code
194
-
- Cowork
195
-
- Cursor
196
-
- Gemini CLI
197
-
- Aider
198
-
- Augment CLI
199
-
- AMP
200
-
- OpenCode
201
-
- OpenClaw
202
-
- GitHub Copilot
203
-
- Replit
204
-
- Devin
205
-
- Google Antigravity
206
-
- Pi
207
-
- Kiro CLI
208
-
- Windsurf
209
-
- Cline
210
-
- Roo Code
211
-
- Kilo Code
212
-
- Mistral Vibe
213
-
- v0
143
+
```sh
144
+
cargo install agenthint
145
+
agenthint --json
146
+
```
214
147
215
-
Custom agents are supported through any non-empty `AI_AGENT` value.
148
+
### PyPI
216
149
217
-
See [docs/agents.md](docs/agents.md) for recommended `AI_AGENT` values.
150
+
```sh
151
+
python3 -m pip install agenthint
152
+
agenthint --json
153
+
```
218
154
219
-
See [docs/integrations.md](docs/integrations.md) for Bash, Zsh, Fish, Node.js, Rust, and Python integration snippets.
155
+
### Native binary
220
156
221
-
See [docs/signals.md](docs/signals.md) for the signal registry and confidence levels.
157
+
```sh
158
+
curl -fsSL https://raw.githubusercontent.com/forjd/agenthint/main/install.sh | sh
159
+
```
222
160
223
-
## Principles
161
+
The install script downloads the latest `agenthint-v*` GitHub Release asset for your platform and verifies `SHA256SUMS` when the selected release provides them.
224
162
225
-
- Detection is advisory and can be spoofed.
226
-
- Prefer `AI_AGENT` when an agent can set an explicit hint.
227
-
- Prefer explicit environment signals over brittle heuristics.
228
-
- Return confidence, not false certainty.
229
-
- Print signal names, not environment variable values.
230
-
- Keep output quiet and machine-readable when requested.
231
-
- Make the convention useful across languages and toolchains.
163
+
Override the install directory or version:
232
164
233
-
## Packages
234
-
235
-
Current:
165
+
```sh
166
+
AGENTHINT_INSTALL_DIR=/usr/local/bin sh install.sh
167
+
AGENTHINT_VERSION=agenthint-vX.Y.Z sh install.sh
168
+
```
236
169
237
-
-`agenthint` JavaScript/TypeScript package
238
-
-`agenthint` Rust crate and CLI implementation
239
-
-`agenthint` Python package
170
+
## Detection Model
240
171
241
-
Planned:
172
+
Every detection result includes:
242
173
243
-
- standalone native binary releases
174
+
| Field | Description |
175
+
| --- | --- |
176
+
|`isAgent`| Whether an agent runtime is likely detected |
177
+
|`agent`| Known or custom agent name, when available |
178
+
|`confidence`| A number from `0` to `1`|
179
+
|`signals`| Diagnostic signal names, never secret values |
244
180
245
-
The packages use the unscoped `agenthint` name across npm, crates.io, and PyPI. If the npm name becomes unavailable before first publish, the fallback package name is `@forjd/agenthint`.
Known agents include Codex, Claude Code, Cursor, Gemini CLI, Aider, Augment CLI, AMP, OpenCode, OpenClaw, GitHub Copilot, Replit, Devin, Google Antigravity, Pi, Kiro CLI, Windsurf, Cline, Roo Code, Kilo Code, Mistral Vibe, v0, and Cowork.
250
192
251
-
Releases use release-please with Conventional Commits. npm and PyPI publishing use trusted publishing via GitHub Actions OIDC, so no long-lived package tokens are required.
193
+
Custom agents are supported through any non-empty `AI_AGENT` value.
252
194
253
-
See [docs/releases.md](docs/releases.md) for release details.
`agenthint` is not an authentication, authorization, sandboxing, or policy tool. Environment variables, parent process names, and filesystem markers can be spoofed. Treat all results as UX hints only.
Contributions are welcome. Please keep detection results explainable, avoid printing secret-bearing environment values, and update the docs when adding or changing signals.
0 commit comments