Skip to content

About

A repository for agentlogger

Resources

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

11 Commits

Folders and files

Repository files navigation

AgentLogger Banner

AgentLogger

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.

status server sdk license


Quick start

# 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.demo

That's it. Every iOS launch that bootstraps the SDK appears in agentlog sessions list.


Add to an existing iOS app

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.


CLI essentials

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 cheatsheet

Append --json to any read command for NDJSON output (one record per line).


Running the daemon

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).


Agent integration

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.


How it works

┌─────────────────────────────┐         ┌──────────────────────────────┐
│ 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.


Project layout

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)

Adding a new SDK (Kotlin / JS / Dart / …)

Two contracts every SDK obeys:

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>/.


Development

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 targets

License

TBD.

About

A repository for agentlogger

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages