Readme
Agent-First HTTP
Persistent HTTP client for AI agents — one request, one JSON line.
Supported platforms: macOS, Linux, Windows.
Modes (single entrypoint):
--mode cli --mode pipe --mode mcp --mode curl
The key contract for agents is protocol determinism: stdout { " code" : " error" , ... } error_code
CLI Mode
The default mode — one request, one JSON response, exit:
afhttp GET https://api.example.com/users
# {"code":"response","status":200,"body":[...],"trace":{"duration_ms":120,...}}
afhttp POST https://api.example.com/users --body '{"name":"Alice","email":"alice@example.com"}'
# {"code":"response","status":201,"body":{"id":42},...}
afhttp GET https://api.example.com/data --header "Authorization: Bearer sk-xxx"
# {"code":"response","status":200,...}
Structured error output examples:
{ " code" : " error" , " error_code" : " connect_timeout" , " error" : " request timed out after 30s" , " retryable" : true , " trace" : { " duration_ms" : 30012 } }
{ " code" : " error" , " error_code" : " invalid_request" , " error" : " invalid --output format 'xml': expected json, yaml, or plain" , " retryable" : false , " trace" : { " duration_ms" : 0 } }
Pipe Mode
For long-lived sessions with connection reuse, concurrent requests, and WebSocket — use afhttp - - mode pipe
afhttp -- mode<< ' EOF ' EOF
output:
{ " code" : " config" , " host_defaults" : { " api.example.com" : { " headers" : { " x-api-key" : " [redacted]" , " api-version" : " 2023-06-01" } } } , . . . }
{ " code" : " response" , " id" : " models" , " status" : 200 , " body" : { " data" : [ { " id" : " general-chat-model" , . . . } ] } , " trace" : { " duration_ms" : 92 , " http_version" : " h2" , " redirects" : 0 , " remote_addr" : " 13.32.4.10" } }
{ " code" : " response" , " id" : " usage" , " status" : 403 , " body" : { " error" : { " type" : " permission_error" , " message" : " Your API key does not have permission" } } , " trace" : { " duration_ms" : 87 , " http_version" : " h2" , " redirects" : 0 } }
{ " code" : " chunk_start" , " id" : " chat" , " status" : 200 , " headers" : { " content-type" : " text/event-stream" } }
{ " code" : " chunk_data" , " id" : " chat" , " data" : " event: content_block_delta\n data: {\" delta\" :{\" text\" :\" Hello\" }}" }
{ " code" : " chunk_data" , " id" : " chat" , " data" : " event: content_block_delta\n data: {\" delta\" :{\" text\" :\" there\" }}" }
{ " code" : " chunk_data" , " id" : " chat" , " data" : " event: message_stop\n data: {}" }
{ " code" : " chunk_end" , " id" : " chat" , " trace" : { " duration_ms" : 834 , " chunks" : 8 } }
What just happened:
One bash call — the heredoc sends all requests into one afhttp Auth set once per host — host_defaults Three requests fired without waiting — models usage chat Connection reuse is automatic — requests to the same host can reuse pooled connections without extra agent logicOut-of-order responses — usage chat id Streaming inline — chat HTTP errors are data — usage code: " response" status: 403 status
MCP Mode
afhttp - - mode mcp Model Context Protocol server, letting AI tools like Claude Desktop make HTTP requests directly:
{
" mcpServers" : {
" afhttp" : { " command" : " afhttp" , " args" : [ " --mode" , " mcp" ] }
}
}
Claude can then call http_request http_config docs/mcp.md for the full setup guide.
curl Compatibility
Use explicit curl mode. afhttp understands a subset of curl flags and returns structured JSON:
afhttp -- mode - X-H " Authorization: Bearer sk-xxx"
-d ' {"name":"Alice"}'
# {"code":"response","status":201,"body":{"id":42},...}
Install
macOS / Linux — Homebrew
brew install cmnspore/tap/afhttp
Windows — Scoop
scoop bucket add cmnspore https:/ / github.com / cmnspore/ scoop- bucket
scoop install afhttp
Any platform — Cargo
cargo install agent-first-http
Docs
License
MIT