# Agent Trail: לראות מה סוכן ה-AI שלכם באמת עושה, בזמן אמת, מקומית

> Agent Trail (בשם החבילה: agenttrail) הוא כלי קוד פתוח שנותן לכם שכבת תצפית מקומית על סוכני הקוד שלכם. במקום לקרוא מאות שורות בטרמינל ולנחש אם הסוכן מתקדם, אתם מקבלים לוח חי בדפדפן שמראה מה קורה בפרויקט ברגע זה.

מאת קווין ליאקס. פורסם 2026-08-31. נושא: סוכנים.
העמוד המלא: https://kevinliaks.ai/guides/agent-trail

## מה זה Agent Trail

Agent Trail (בשם החבילה: `agenttrail`) הוא כלי קוד פתוח שנותן לכם שכבת תצפית מקומית על סוכני הקוד שלכם. במקום לקרוא מאות שורות בטרמינל ולנחש אם הסוכן מתקדם, אתם מקבלים לוח חי בדפדפן שמראה מה קורה בפרויקט ברגע זה.

הכלי משוחרר ברישיון MIT, כתוב ב-Node, ורץ אך ורק על המחשב שלכם. אין חשבון, אין התקנה גלובלית, אין טלמטריה, ושום דבר לא נשלח החוצה.

**הרעיון המרכזי: תוכנית מספרת מה הסוכן מתכוון לעשות, ומערכת הקבצים מספרת מה הוא באמת נגע בו. Agent Trail מציג את שניהם זה לצד זה, וכשהם לא מסתדרים, אתם יודעים בדיוק לאן להסתכל.**

## הבעיה שהוא פותר

אתם נותנים ל-Claude Code משימה גדולה. הטרמינל מתחיל לרוץ: קורא קובץ, עורך משהו, מריץ פקודה, חוזר לקובץ אחר. אחרי עשר דקות אתם מסתכלים על השורות ולא יודעים אם הוא מתקדם או מסתובב במעגל, ואם הוא במקרה פתח מחדש חלק שכבר הכריז עליו כגמור.

תמלול של הרצה לא עונה על זה. מה שעונה זו מפה שמתעדכנת תוך כדי.

## איך מתקינים: פקודה אחת

אין מה להתקין. נכנסים לתיקיית הפרויקט ומריצים:

```bash
cd your-repo
npx agenttrail
```

הדפדפן נפתח על הלוח החי, מקומית. כבר מהרגע הזה, בלי שום הגדרה, אתם מקבלים:

- עץ קבצים בסגנון VS Code, עם סימון חי של קבצים שהשתנו זה עתה
- מתי הייתה הפעילות האחרונה בכל קובץ
- כרטיסי הרצה של Claude Code, כולל רשימת המשימות, שורת הכלי שרצה עכשיו וזמן שחלף, כשה-hooks המקומיים מותקנים

**דרישה יחידה: Node בגרסה 20 ומעלה.**

![הלוח החי: עץ הקבצים משמאל, מפת הרכיבים במרכז, וכרטיס ההרצה הפעילה של הסוכן בפינה](https://kevinliaks.ai/_astro/01.j9LrzIR3.jpg)

*הלוח החי: עץ הקבצים משמאל, מפת הרכיבים במרכז, וכרטיס ההרצה הפעילה של הסוכן בפינה*

## איך בונים את המפה

החלק המעניין באמת מגיע כשמריצים פעם אחת בלבד:

```bash
npx agenttrail init
```

הפקודה הזאת עושה ארבעה דברים:

- יוצרת קובץ PLAN.md התחלתי בשורש הפרויקט
- מוסיפה את המוסכמה של agenttrail לקבצי ההנחיות של הסוכן, CLAUDE.md ו-AGENTS.md
- מתקינה hooks מקומיים של Claude Code (בתוך הפרויקט בלבד, בקובץ .claude/settings.local.json)
- מוסיפה את התיקייה ‎.agenttrail/‎ ל-gitignore

אחר כך לוחצים בלוח על **Copy backfill prompt** ומדביקים את הפרומפט לסוכן. הוא קורא קודם את הקוד, אחר כך את היסטוריית ה-git, ורק בסוף את מסמכי התכנון, ומצייר את הפרויקט כ-5 עד 9 רכיבים עם תלויות אמיתיות וסטטוסים שניתן לאמת.

**מהרגע הזה אתם לא מתחזקים לוח ניהול משימות. הסוכנים שלכם מתחזקים קובץ Markdown קטן אחד תוך כדי עבודה.**

![רכיב פתוח עם רשימת המשימות שלו, מה הושלם, מה בעבודה, ואיזה קבצים נגעו בו](https://kevinliaks.ai/_astro/02.Cdhe0OoL.jpg)

*רכיב פתוח עם רשימת המשימות שלו, מה הושלם, מה בעבודה, ואיזה קבצים נגעו בו*

## מוסכמת PLAN.md

כל המודל מגיע מקובץ אחד. אלה הסימנים שכדאי להכיר:

| סימון | המשמעות |
|---|---|
| `{#id}` | מזהה יציב לרכיב או למשימה, כך הלוח יודע לעקוב אחריהם גם כשהטקסט משתנה |
| `files:` | אילו נתיבים שייכים לרכיב: זה מה שמחבר כתיבה לקובץ לרכיב הנכון במפה |
| `[x]` | המשימה הושלמה |
| `[~]` | המשימה בעבודה עכשיו |
| `[!]` | המשימה תקועה |
| `needs:` | תלות: מצייר חץ בין רכיבים במפה |
| `links:` | קשר רופף: מצייר קו מקווקו |
| `by:` | מי ביצע: claude, openai, או ראשי תיבות של אדם |
| `from:` | מפריד בין כוונה של סוכן לבין פריט שהגיע מה-roadmap |

כך נראה קטע אמיתי מתוך PLAN.md:

```markdown
## Capture the audio {#capture}
tech: coreaudio tap + ring buffer
files: [src/audio/**]
- [x] Grab the mic feed {#capture-mic}
    by: claude
- [~] Keep the last 30 seconds ready {#capture-ring}
    by: claude

## Decide what matters {#classify}
needs: [capture]
- [ ] Score events by urgency {#classify-score}
    from: roadmap
```

## מה רואים בלוח

- מפה של 5 עד 9 רכיבים אמיתיים, עם חצי תלות, קווים מקווקווים והתקדמות לכל רכיב
- סטטוס כן: הושלם, בעבודה או תקוע, ולא אחוזים מומצאים
- ההרצה הנוכחית של Claude Code: רשימת המשימות, הכלי שרץ עכשיו, זמן שחלף וקריאות אחרונות
- התוכנית של הסשן עצמו, בתוך הרכיב שהוא עובד עליו, נמוגה שעתיים אחרי שההרצה נגמרה
- כרטיס שכבר סומן כגמור נדלק מחדש כשקבצים שלו משתנים שוב, כך תופסים חזרה שקטה לחלק שהוכרז סגור
- מתג טאבים לכל הפרויקטים הפעילים: דמון אחד לכל repo, וכל הלוחות בטאב אחד

## אילו סוכנים נתמכים

| סוכן | פעילות חיה | כרטיסי הרצה | מתחזק את המפה |
|---|---|---|---|
| **Claude Code** | **כן** | **כן: דרך hooks** | `CLAUDE.md` |
| **OpenAI Codex** | **כן** | לא | `AGENTS.md` |
| **Cursor וכל השאר** | **כן** | לא | `AGENTS.md` |

המעקב החי עובד לכל סוכן שעורך קבצים, כי הוא מבוסס על צפייה במערכת הקבצים. מה ש-Claude Code מקבל בנוסף זה כרטיסי ההרצה, דרך ה-hooks המקומיים, ולכן שם התמונה הכי עשירה.

## פרטיות: מה באמת קורה אצלכם

- הכלי מאזין ל-127.0.0.1 בלבד. אין חשיפה לרשת.
- אין חשבון, אין שירות ענן, אין טלמטריה, אין שלב build.
- ה-hooks של Claude Code יושבים בתוך הפרויקט, בקובץ .claude/settings.local.json, ומועברים רק לדמון המקומי.
- בזמן שהוא רץ הוא רק צופה, הוא לא שולח פרומפטים ולא עורך את הקוד שלכם.
- הדמון הוא קובץ Node אחד בלי תלויות, בערך 470 שורות. הממשק הוא קובץ HTML סטטי אחד.

## פקודות שכדאי להכיר

| פקודה | מה היא עושה |
|---|---|
| `npx agenttrail` | פותח את הלוח החי לפרויקט הנוכחי ומתחיל לצפות בו |
| `npx agenttrail init` | מקים את PLAN.md, מוסיף את המוסכמה לקבצי ההנחיות ומתקין hooks מקומיים, פעם אחת לפרויקט |
| `npx agenttrail up` | מרים מחדש את כל הלוחות שהרצתם אי פעם, שימושי אחרי אתחול של המחשב |
| `npx agenttrail autostart` | גורם ללוח של הפרויקט לעלות אוטומטית בהתחברות למחשב ולהתאושש מנפילות |

## טיפים

- התחילו בלי init. הריצו npx agenttrail על repo קיים ותראו מיד את עץ הקבצים והפעילות, זה כבר פותר חצי מהבעיה.
- את המפה בונים פעם אחת, וכדאי לעשות את זה על פרויקט שאתם מכירים היטב, כך תזהו מיד אם הסוכן צייר אותו נכון.
- אם התוכנית מתיישנת, פשוט תגידו לסוכן: re-verify PLAN.md against the code. הלוח מתעדכן ברגע שהקובץ מתעדכן.
- שימו לב לכרטיס שנדלק מחדש אחרי שסומן כגמור, זה בדיוק הסימן שהסוכן חזר לחלק שכבר סגר, וזה מה שקשה לתפוס בטרמינל.
- אפשר להוסיף repo נוסף במשפט אחד לסוכן: run npx agenttrail in this repo. הטאב יופיע בכל הלוחות תוך שניות.
- עובד גם על repos ענקיים, נבדק על פרויקט עם 78 אלף קבצים. הוא קורא את העץ לרוחב עם תקרה לכל תיקייה ומודיע לכם כשהתצוגה מקוצרת.
- ה-init הוא תוספתי בלבד: הוא לא מוחק ולא משכתב את CLAUDE.md הקיים שלכם, אלא מוסיף לו.

## מגבלות שכדאי לדעת עליהן מראש

- כרטיסי ההרצה המלאים קיימים כרגע רק ל-Claude Code. Codex ו-Cursor מקבלים מעקב קבצים ותחזוקת מפה, בלי כרטיס ההרצה החי.
- המפה טובה בדיוק כמו PLAN.md. אם אף סוכן לא מתחזק אותו, תישארו עם עץ הקבצים והפעילות בלבד, שימושי, אבל בלי ההקשר.
- צריך Node 20 ומעלה.
- הכלי צופה בלבד. הוא לא מריץ, לא עוצר ולא מתקן את הסוכן בשבילכם.

## לינקים

- ה-repo הרשמי: [github.com/sodiumsun/agenttrail](https://github.com/sodiumsun/agenttrail)
- החבילה ב-npm: [npmjs.com/package/agenttrail](https://www.npmjs.com/package/agenttrail)
- קוד הליבה של הדמון: [bin/agenttrail.mjs](https://github.com/sodiumsun/agenttrail/blob/main/bin/agenttrail.mjs)

---
קווין ליאקס מעביר סדנאות AI, הרצאות והטמעה לארגונים: https://kevinliaks.ai/workshops