setup-agent-tail
Configure agent-tail log aggregation for the current project. Auto-detects framework (Vite, Next.js, plain Node, monorepo) and sets up CLI runner, browser log plugins, and output destinations. Use when setting up agent-tail, configuring dev server logging, or piping logs for AI agent consumption.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 13
- Forks
- 2
01 前言 Front Matter
- name
- setup-agent-tail
- description
- Configure agent-tail log aggregation for the current project. Auto-detects framework (Vite, Next.js, plain Node, monorepo) and sets up CLI runner, browser log plugins, and output destinations. Use when setting up agent-tail, configuring dev server logging, or piping logs for AI agent consumption.
03 SKILL.md 正文
<objective> Configure agent-tail for the current project. Agent-tail pipes logs from dev servers and browser consoles into unified log files that AI coding agents can read and grep. This skill auto-detects the project type, proposes a configuration, and sets everything up after user confirmation. </objective>
<quick_start> Run the auto-detect workflow below. The skill will:
- Detect project framework and structure
- Propose a configuration
- Install agent-tail after user confirms
- Configure framework plugins, CLI scripts, and gitignore </quick_start>
<essential_principles>
- Logs are written to
tmp/logs/latest/— this is agent-tail's standard output directory - The
tmp/directory must be gitignored - Browser log capture requires a framework plugin (Vite or Next.js) in addition to the CLI
- For monorepos, use
agent-tail-core initat root andagent-tail-core wrapin each package - Always confirm the proposed configuration with the user before making changes </essential_principles>
<process> Step 1: Detect project type
Read these files to determine the project setup:
package.json— check for framework dependencies (vite, next, react, etc.) and existing scriptsvite.config.ts/vite.config.js— Vite project indicatornext.config.ts/next.config.js/next.config.mjs— Next.js project indicatorturbo.json/nx.json/pnpm-workspace.yaml/lerna.json— monorepo indicators.gitignore— check iftmp/is already ignored
Classify the project as one of:
- vite — Vite-based project (React, Vue, Svelte, etc.)
- nextjs — Next.js project
- monorepo — Turborepo, Nx, pnpm workspaces, or Lerna
- node-cli — Plain Node.js / any other project (CLI-only setup)
Step 2: Gather user preferences
Use AskUserQuestion to confirm detection and gather preferences:
Question 1: "I detected a [framework] project. Is this correct?"
- Yes, proceed
- No, it's actually [other options]
Question 2: "Which services should agent-tail manage?"
- Based on detected scripts in package.json (e.g., "dev", "api", "worker")
- Let user add custom service names and commands
Question 3: "Configure output destinations?"
- Default (tmp/logs/latest/) (Recommended)
- Custom directory
- Custom directory with combined.log disabled
Question 4: "Set up browser console log capture?"
- Yes (Recommended) — if Vite or Next.js detected
- No, server logs only
- [Skip this question for node-cli projects]
Step 3: Install agent-tail
# Detect package manager from lockfile
# bun.lock → bun
# pnpm-lock.yaml → pnpm
# yarn.lock → yarn
# package-lock.json → npm
<pkg-manager> add -D agent-tail agent-tail-core
Important: The agent-tail umbrella package has a broken bin field that prevents the CLI from being linked. You must also install agent-tail-core explicitly — this is the package that provides the actual agent-tail-core CLI binary. Use agent-tail-core (not agent-tail) as the command name in all scripts.
Step 4: Configure framework plugin
For each detected framework, apply the appropriate configuration. See references/framework-configs.md for exact code.
- Vite: Add
agentTail()plugin to vite.config - Next.js: Wrap config with
withAgentTail(), addAgentTailScriptto layout, create browser log API route - Monorepo: Add
agent-tail initto root dev script, wrap each package withagent-tail wrap - Node CLI: No plugin needed, just CLI configuration
Step 5: Configure package.json scripts
Update package.json scripts to use agent-tail-core CLI. Transform existing dev scripts:
{
"scripts": {
"dev": "agent-tail-core run '<service1>: <original-command>' '<service2>: <original-command>'"
}
}
If user specified excludes or muting, add flags:
{
"scripts": {
"dev": "agent-tail-core run --exclude '[HMR]' --mute worker '<services>'"
}
}
Step 6: Update .gitignore
Add tmp/ to .gitignore if not already present.
Step 7: Verify setup
After configuration, tell the user:
- Run their dev script to verify logs appear in
tmp/logs/latest/ - Check that individual service logs and
combined.logare created - If browser logging was enabled, verify console output appears in the browser log file </process>
<configuration_options> These options can be presented to the user during setup:
Output directory: Where logs are written (default: tmp/logs/latest/)
Excludes: Filter noisy log lines by substring or regex:
- Common Vite excludes:
[HMR],[vite],Download the React DevTools - Common Next.js excludes:
[Fast Refresh],compiled successfully
Service muting: Hide specific services from terminal output while preserving log files:
- Useful for noisy frontend dev servers when focused on backend work
Browser log capture: Capture console.*, unhandled errors, and unhandled promise rejections from the browser
Log format: All logs use timestamp + level + message format:
[10:30:00.123] [LOG ] Message here
Gitignore warning: Agent-tail warns on startup if tmp/ is not gitignored. Disable with warnOnMissingGitignore: false in plugin options.
</configuration_options>
<anti_patterns> <pitfall name="forgetting-browser-setup"> For Vite/Next.js projects, the CLI alone does not capture browser console logs. The framework plugin is required for browser log capture. </pitfall>
<pitfall name="monorepo-without-init">
In monorepos using Turborepo/Nx, you must run agent-tail-core init before turbo dev (or equivalent). Without init, agent-tail-core wrap in child packages has no session to join.
</pitfall>
<pitfall name="using-agent-tail-cli-instead-of-agent-tail-core">
The agent-tail umbrella package has a broken bin field — it references a nested path that package managers don't resolve correctly. Always use agent-tail-core as the CLI command in scripts, and always install agent-tail-core as an explicit devDependency alongside agent-tail.
</pitfall>
<pitfall name="overwriting-existing-scripts"> When modifying package.json scripts, preserve the original command inside the agent-tail runner. Do not replace the command, wrap it. </pitfall> </anti_patterns>
<success_criteria> Setup is complete when:
- agent-tail is installed as a dev dependency
- Framework plugin configured (if Vite or Next.js)
- package.json dev script wraps services with agent-tail
tmp/is in .gitignore- User has been told how to verify the setup works </success_criteria>
<reference_guides> Framework-specific configuration code: See references/framework-configs.md </reference_guides>
04 同仓库更多 Skills
openai--sentry--sentry
Use when the user asks to inspect Sentry issues or events, summarize recent production errors, or pull basic Sentry health data via the Sentry API; perform read-only queries with the bundled script and require `SENTRY_AUTH_TOKEN`.
ito-basket-compare
Compare Itô prediction-market baskets against a user's knowledge base, portfolio notes, financial context, watchlist, or research thesis. Use for read-only basket comparison and gap analysis without investment advice or live trading.
implementing-network-traffic-baselining
Build network traffic baselines from NetFlow/IPFIX data using Python pandas for statistical analysis, z-score anomaly detection, and hourly/daily traffic pattern profiling
detecting-evasion-techniques-in-endpoint-logs
Detects defense evasion techniques used by adversaries in endpoint logs including log tampering, timestomping, process injection, and security tool disabling. Use when investigating suspicious endpoint behavior, building detection rules for evasion tactics, or conducting threat hunting for stealthy adversary activity. Activates for requests involving evasion detection, defense evasion analysis, log tampering detection, or MITRE ATT&CK TA0005.
implementing-microsegmentation-with-guardicore
Implementing microsegmentation using Akamai Guardicore Segmentation to map application dependencies, create granular network policies, visualize east-west traffic flows, and enforce least-privilege communication between workloads across data centers and cloud.
ramdisk-tmpfs-patterns
暂无简介