Skip to content

For the complete documentation index, see llms.txt.

Frequently asked questions

This page answers questions about setting up an Instruction Hub, collecting agent sessions, deploying and updating the analyzer, and acting on findings. Each answer links to the page with the full procedure or explanation.

QuestionAnswerMore information
Can we use an Instruction Hub without deploying an analyzer?Yes. Publish and install your instructions with trace_ingestion.enabled: false, the default. That workflow needs no worker, database, bucket, or model-provider credentials.Set up your Instruction Hub
Do we have to move every AGENTS.md or CLAUDE.md into the hub?No. Move reusable instructions into shared hub assets, and keep repository-specific context beside the project it describes. pig scan records root context files in its inventory but doesn’t turn them into shared skills.Migrate existing instructions
What does pig scan import automatically?Skills from .agents/skills, .claude/skills, and .cursor/skills, plus supported root or Cursor MCP configuration. Other layouts and asset kinds need a reviewed manual migration. Scan one source at a time and inspect the diff, because the scan can replace an existing asset with the same ID.Migrate existing instructions, for inventory, naming conflicts, and pilot rollout
Why is the pig plugin required?It’s the canonical home for the toolchain-managed update skill and the optional collection integration, and it can hold shared assets. Keep pig in stable_plugins, and organize other instructions into plugins such as Acme’s docs and dev.The required pig plugin
Can we publish from GitLab?Yes. Hub publishing supports GitHub Actions and GitLab CI. Agent installation support varies, so test your team’s desktop importer, particularly Cursor with a GitLab repository. The analyzer’s hub binding and remediation require GitHub and a main branch.Publish and install plugins
QuestionAnswerMore information
Which agents does PIG support?The toolchain builds instructions for Claude, Codex, Cursor, and Gemini. Native trace collection is a separate capability: it supports Claude Code, Claude Desktop, Codex, and, with analyzer 0.3.3 or later, Cursor desktop sessions. Building a Gemini plugin doesn’t enable collection for Gemini.Supported agents
What leaves an enrolled host?The collector uploads native session records and related collection metadata to your analyzer. Your configured model provider receives analysis input. Promptless receives trace status, findings, and evidence summaries, which can describe session details.Trust and data model
Does enrolling a host upload its old sessions?It can. When a discovered native source has no acknowledged upload position, collection starts from the beginning and can upload existing session history. Later collection resumes from the position in the upload ledger. Agree on pilot hosts and repositories before enrollment, then verify a new session.Enroll your hosts
Does disabling trace ingestion delete data?No. A release published with trace ingestion disabled leaves out the managed collection hooks, and each host keeps its hooks until it refreshes its installed plugins. Stored traces, findings, and the analyzer deployment remain, so manage their retention separately.Trust and data model
QuestionAnswerMore information
What does the analyzer need to run?A Kubernetes deployment, PostgreSQL, native object storage, a Promptless deployment token, and network access between those systems. Analysis also needs a configured model provider and instruction repositories selected in PIG Settings. Each selected repository is a GitHub repository with a main branch.Plan your deployment
Can we deploy on Azure or Google Cloud?Azure and Google Cloud are experimental. The current stable release, PIG 0.3.6, targets only AWS (EKS). The Azure and Google Cloud guides are for evaluation. On every cloud, Terraform prepares the infrastructure before the common Helm bootstrap.AWS, Azure, and GCP guides, for prerequisites and configuration
Does the trace analyzer update automatically?Yes. By default it updates to stable releases, and you can pause updates or pin a release. The supervisor coordinates application and schema updates. Operators apply required infrastructure changes, such as databases, storage, cloud identities, and networking, through Terraform.Manage updates and recovery
Can we schedule and apply every upgrade ourselves?Yes. Choose manually managed Helm during installation.Manually managed Helm
Does a healthy pod mean analysis is working?No. The health endpoint doesn’t cover the whole path. Verify that an enrolled host can upload, the trace is stored, and analysis completes. A completed analysis can produce no finding.Observability
How do we verify plugin installation across our hosts?Track rollout through your release and enrollment records, and run the plugin installation checks on each host. Enrollment and trace collection don’t prove that every plugin is installed and loaded.Publish and install plugins
QuestionAnswerMore information
Does PIG merge instruction changes automatically?The documented workflow produces a proposed pull request for your team to review. Apply your repository’s checks and merge controls before you publish a new hub release.Remediate findings
Does every finding need an instruction change?No. A finding can call for work on a tool, integration, or external system. Review the explanation and evidence before you decide who acts on it.Understand findings
Which systems use GitHub credentials?Promptless gives the analyzer GitHub App tokens, scoped to Contents read, for the instruction repositories selected in PIG Settings. Promptless also uses the connected GitHub integration to coordinate issues, and provides repository-scoped credentials for remediation tasks. Operators don’t configure a GitHub token for the analyzer.Select instruction repositories

Email help@gopromptless.ai for setup or deployment help. Include these details:

DetailWhat to send
Affected componentThe hub toolchain, an enrolled host, or the analyzer deployment
VersionThe deployment or hub version
Failed stepThe step that failed
DiagnosticsRedacted diagnostics. Don’t send credentials or raw session transcripts.