Guides

Sync & advise

The start-of-session sync call, what it returns, how to present it — and advise, which proposes setup changes for your harness.

Sync — once per session

codexguild_sync (MCP) / POST /agents/me/sync (REST) answers one question: what changed that matters to this project since I last looked?

bash

curl -s -X POST https://api.codexguild.com/v1/agents/me/sync \
  -H "Authorization: Bearer $CODEXGUILD_API_KEY" -H "content-type: application/json" \
  -d '{
    "stack": [{"name":"next","version":"15.3.0"},{"name":"@prisma/client","version":"6.19.0"}],
    "installedSkills": ["frontend-design","mcp-builder"]
  }'

Field	Type	Notes
`stack`	`{name, version?, ecosystem?}[]` (≤300)	Dependency names and versions only. `ecosystem` is `npm` (default), `pypi`, `go` or `cargo` — send `pypi` for Python packages so PyPI `openai` gets the Python SDK's releases, not the npm one's. Omit `stack` to reuse the last reported one.
`installedSkills`	`string[]` (≤500)	Names of skills in your skills folders.
`since`	ISO date or datetime	Defaults to your last sync; 30 days on the first one. Implies a refresh.
`force`	boolean	Full refresh now, regardless of the refresh frequency (before a dependency upgrade, or when you ask).

Call sync at the start of every session. You choose per agent, in the dashboard (Agents → Refresh), how often it gets a full refresh: every session, daily (default), weekly, every 15 days or monthly. Between refreshes sync answers "mode": "up_to_date" with nextRefreshAt and only urgent items — new security advisories and installed skills the scanner now flags — so it costs a few tokens and no freshness quota. A new dependency in stack, since or force triggers a refresh early. Independently, the dashboard Alerts inbox gets new advisories, breaking releases and flagged skills that match your agents' stacks within the hour.

Package names are normalized to topics: next → nextjs, @nestjs/core → nestjs, @prisma/client → prisma.

Response

json

{
  "syncedAt": "2026-09-29T08:00:00.000Z",
  "since": "2026-08-30T08:00:00.000Z",
  "firstSync": false,
  "stack": { "deps": 42, "trackedTopics": ["nextjs", "prisma"], "untrackedTopics": ["zod"] },
  "freshness": [{
    "topic": "nextjs", "yourVersion": "15.3.0", "total": 12, "breaking": 1,
    "changes": [{ "title": "v16.0.0", "versionTag": "v16.0.0", "breaking": true, "asOf": "…", "url": "…" }]
  }],
  "security": {
    "installedSkills": [{ "slug": "…", "name": "mcp-builder", "securityStatus": "passed", "counts": {}, "stale": false }],
    "unknownSkills": ["my-private-skill"],
    "advisories": [{ "slug": "…", "title": "…", "summaryMd": "…", "asOfDate": "…" }]
  },
  "kb": [{ "slug": "…", "title": "…", "asOfDate": "…" }],
  "recommendedSkills": [{ "slug": "…", "name": "…", "category": "frontend", "matches": ["nextjs"], "installCommand": "…" }]
}

How your agent should present it

Keep it short and actionable:

Possibly-breaking releases for the project's stack, with yourVersion so the user can tell "patch for my line" from "next major".
Installed skills that are flagged or warn, or stale (its source repository has had no commits for roughly ten months or more — likely unmaintained).
New advisories for coding agents.
Recommendations only if the user asks — never install automatically.

Tip: unknownSkills are skills CodexGuild has never seen (private or local). Run codexguild_scan_skills from the local MCP server to audit them offline.

Sync counts as one freshness call against your daily quota.

Advise — set the agent up

codexguild_advise / POST /agents/me/advise returns proposals, never changes: