Ship app logs to a local daemon, query them from a CLI.
For AI agents that drive apps from the terminal and need their runtime logs.
# 1. Install the daemon binary (→ /usr/local/bin) + Claude Code skills
./scripts/install.sh --from-source
# 2. Start it
agentlog start &
agentlog status # → running
# 3. Smoke test with the bundled demo (boots iPhone Simulator first if needed)
open -a Simulator
make demo-run
# 4. Read its logs
agentlog tail --bundle com.agentlogger.demoThat's it. Every iOS launch that bootstraps the SDK appears in agentlog sessions list.
Step 1 — depend on the package. In Xcode: File → Add Package Dependencies → Add Local… and point at this repo's sdks/swift/ folder. Or in Package.swift:
.package(url: "https://github.com/MarveleE/agent-logger.git", from: "0.1.0")Step 2 — bootstrap once at startup.
import AgentLogger
@main
struct MyApp: App {
init() {
#if DEBUG
AgentLogger.bootstrap()
#else
AgentLogger.bootstrap(.disabled)
#endif
}
var body: some Scene { WindowGroup { ContentView() } }
}Step 3 — log.
AgentLogger.info("user logged in", metadata: ["userId": "42"])
AgentLogger.error("decoding failed", error: err)
AgentLogger.category("Network").debug("GET /users → 200")Step 4 — wire the endpoint into your build.
Standard Xcode pattern: a Build Setting flows into Info.plist via $(VAR)
substitution. One-time project change, then every build (Xcode, xcodebuild,
TestFlight, CI) picks it up.
In your Info.plist, add once:
<key>AgentLoggerEndpoint</key>
<string>$(AGENTLOGGER_ENDPOINT)</string>
<key>NSLocalNetworkUsageDescription</key>
<string>Ships debug logs to your Mac during development.</string>
<key>NSAppTransportSecurity</key>
<dict><key>NSAllowsLocalNetworking</key><true/></dict>Both the iOS Simulator and real devices on the same WiFi are LAN clients
talking to the Mac. Use the same http://<mac>:8765 for both — detect the
Mac's LAN address at build time so the build pipeline works for either
destination unchanged:
MAC_IP="$(ipconfig getifaddr en0 || echo 127.0.0.1)"
xcodebuild build -scheme MyApp -workspace MyApp.xcworkspace -configuration Debug \
-destination "$DESTINATION" \
AGENTLOGGER_ENDPOINT="http://${MAC_IP}:8765"Build-setting precedence is CLI > xcconfig > project file, so each
developer can override on their own machine — gitignore a Local.xcconfig
with your current LAN IP if you want Xcode IDE Run to work without flags.
The daemon listens on 0.0.0.0 by default; restrict with --bind 127.0.0.1
on untrusted networks.
For full coverage of every xcodebuild / simctl / devicectl flow, see
docs/integrating-xcodebuild.md.
agentlog status # is the daemon up?
agentlog sessions latest --bundle <id> --json # newest run
agentlog logs --bundle <id> --level error --since 5m # what blew up?
agentlog tail --bundle <id> # live stream
agentlog search "<phrase>" --bundle <id> # FTS across history
agentlog instances list # all running daemons
agentlog db prune --before 7d # housekeeping
agentlog --help # full cheatsheetAppend --json to any read command for NDJSON output (one record per line).
Two options:
| When | How |
|---|---|
| Development | agentlog start (foreground; Ctrl-C to stop) or make server-start |
| Background | agentlog start & (Unix) / start "" /B agentlog start (Windows). Wrap in launchd / systemd / nssm yourself if you want it supervised. |
Common flags: --port 8765, --bind 0.0.0.0 (real-device access), --data-dir <path>. Stop with agentlog stop.
Multi-instance: spin up multiple daemons by giving each its own --port + --data-dir. agentlog instances list shows all live daemons; agentlog instances stop-all shuts them down in one go.
Cross-platform: the daemon ships as a single static-linked binary for macOS (universal), Windows (amd64/arm64), and Linux (amd64/arm64). make release produces all of them. Stop semantics: Unix uses SIGTERM, Windows uses a loopback-only HTTP shutdown endpoint — same agentlog stop command on both.
Data lives in ~/.agentlog/ (agentlog.sqlite, agentlog.pid, agentlog.port, server.log).
Bundled Claude Code skills under .claude/skills/:
agentlogger-investigate— auto-triggers when the user reports a runtime symptom; pulls logs before guessing. Platform-agnostic.agentlogger-new-sdk— on-ramp for contributors adding SDKs for new languages.
After ./scripts/install.sh they're copied into ~/.claude/skills/ for global availability.
┌─────────────────────────────┐ ┌──────────────────────────────┐
│ App (sim / device / web) │ HTTP │ Mac (your dev machine) │
│ AgentLogger SDK (zero-dep) │ ──────▶ │ agentlog server :8765 │
│ one-line bootstrap │ batch │ └ SQLite (WAL + FTS5) │
└─────────────────────────────┘ │ agentlog tail / logs / … │
└──────────────────────────────┘
Endpoint resolution (in .auto mode): Info.plist AgentLoggerEndpoint → AGENTLOGGER_ENDPOINT env. No mDNS, no auth, no implicit localhost fallback — if neither is configured the SDK silently disables. Explicit by design.
server/ Go daemon + CLI (single binary, no CGO)
sdks/swift/ iOS / macOS SDK (Foundation only, iOS 13+)
demo/ SwiftUI sample app wired to the local SDK
docs/ Wire protocol + SDK behavior contracts
scripts/ install.sh
.claude/skills/ Agent skills (bundled)
Two contracts every SDK obeys:
docs/wire-protocol.md— HTTP + JSON shapes, idempotency, status codesdocs/sdk-behavior.md— 14 behavior clauses (bootstrap, queue, backoff, discovery, …)
Open the repo in Claude Code and say "add a Kotlin SDK" — the bundled agentlogger-new-sdk skill turns the contracts into a step-by-step recipe with per-language patterns and a PR checklist. New SDKs go under sdks/<lang>/.
make doctor # toolchain check
make build # → bin/agentlog
make test # Go + Swift unit tests
make test-e2e # full end-to-end (server + SDK)
make demo-run # build + install + launch demo on booted simulator
make help # all targetsTBD.
