agentdex

package module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 10, 2026 License: MPL-2.0 Imports: 17 Imported by: 0

README

agentdex

agentdex indexes AI coding agents, the models.dev providers that power them, and the models those providers offer — and serves all three as browsable data.

For each catalogued agent it reports the outside facts: whether it is installed, where its binary lives, its version, config and skills directories, which model provider(s) it uses, and (from models.dev) the models available to it. Providers and models are queryable on their own. It never reads an agent's internal configuration, so other tools can resolve paths and capability without hardcoding product layouts.

Ships as a Go library and a thin CLI over it. Only catalogued agents are reported (never arbitrary PATH executables). The catalog is fetched from the CUE Central Registry at runtime and cached, so the known-agent set can change without an agentdex release.

Install

Targets Linux, macOS, and WSL only (see Platforms). First run needs network access to resolve the agent catalog (and models.dev when enrichment is requested). Later runs can work offline from cache; see Catalog and caching.

CLI

Homebrew (Linux/macOS):

brew tap p3bot/tap
brew trust p3bot/tap
brew install p3bot/tap/agentdex

Go:

go install github.com/p3bot/agentdex/cmd/agentdex@v1.0.0
Library
go get github.com/p3bot/agentdex@v1.0.0

require github.com/p3bot/agentdex v1.0.0

CLI

Noun groups (agents, models, providers, each aliased to its singular) with shared verbs list and get.

agentdex agents list [filter]     catalogued agents with local detection
agentdex agents get <id>          detail for one agent (aliases: view, show)
agentdex models list [filter]     models across providers (newest release first)
agentdex models get <id>          one model by provider-id/model-id
agentdex providers list [filter]  models.dev providers and API-key env status
agentdex providers get <id>       detail for one provider
agentdex refresh [target]         force refresh: catalog | models.dev | all
agentdex version
agentdex completion               shell completion script
Quickstart
agentdex agents list

ID           NAME                VERSION  PROVIDERS       MODELS  BIN
claude-code  Claude Code         2.1.220  anthropic       13      /usr/local/bin/claude
codex        Codex CLI           -        openai          47      missing
opencode     opencode            -        -               -       missing

Installed agents lead; other rows show missing when the binary is not on PATH. --installed keeps only detected agents. Agnostic agents (no home provider) show - under providers/models unless you pass --provider.

agentdex agents get claude-code

Agent
id                claude-code
name              Claude Code
version           2.1.220
bin               /usr/local/bin/claude (found)
config_dir        /home/you/.claude
config_local_dir  /home/you/project/.claude
skills_dir        /home/you/.claude/skills
skills_local_dir  /home/you/project/.claude/skills
providers         anthropic
homepage          https://github.com/anthropics/claude-code

Skills
  global
    native  /home/you/.claude/skills (exists)
  local
    native  /home/you/project/.claude/skills (missing)

Provider env
  ANTHROPIC_API_KEY (unset)

Models on agents get are off by default; pass --models (or include models in --fields) to fill them.

agentdex providers list
agentdex providers get anthropic --models
agentdex models list --provider anthropic
agentdex models list --agent claude-code
agentdex models get anthropic/claude-sonnet-4-5

A provider-agnostic --agent on models list also requires --provider.

Flags

Global:

Flag Effect
--json JSON envelope on stdout (see below)
--color auto|always|never Table colour (default auto)
--verbose / --quiet More or less text detail
--debug Diagnostic logging on stderr

On every list and get:

Flag Effect
--fields Select output fields (csv)

On every list:

Flag Effect
--order-by Sort by field (models list default: newest release; others: id)
--reverse Flip sort direction

On agents:

Flag Effect
--installed list: only agents detected on this machine
--provider models.dev provider ids for agnostic agents (repeatable or csv)
--models get: fill the per-model list
--search-dir Extra binary search locations (repeatable)
--bin-path id=path Override an agent's binary path (repeatable)

On models list:

Flag Effect
--provider Scope to models.dev provider ids
--agent Scope to a catalogued agent's providers

On providers get:

Flag Effect
--models Fill the per-model table
JSON envelope
agentdex --json agents list --installed

{
  "status": "ok",
  "data": [
    {
      "id": "claude-code",
      "found": true
    }
  ],
  "warnings": []
}

Each element of data carries the selected fields for that command (more than id and found by default). On failure: "status": "error" with "error" set; warnings may still be present. data is omitted or empty as appropriate.

Exit codes
Code Meaning
0 Success
1 Failure
2 Usage
3 Not found
4 Permission
75 Transient (catalog or models.dev unavailable)
78 Config (invalid config.cue, invalid catalog, models.dev schema drift)
CLI configuration

Optional and CLI-only. Library callers use Open options, not this file.

Path: $XDG_CONFIG_HOME/agentdex/config.cue (fallback ~/.config/agentdex/config.cue). Absent file means defaults. Flags override config on collision.

cache_ttl?: string // fallback TTL when section ttl omitted

catalog: {
	module: string | *"github.com/p3bot/agentdex/catalog@v1"
	dir?:   string // local CUE module (no registry; never stale)
	ttl?:   string // version-resolution TTL (default 24h)
}

models: {
	url?: string
	ttl?: string // default 24h
}

search_dirs?: [...string]
bin_paths?: [string]: string
color: "auto" | "always" | "never" | *"auto"

Use catalog.dir to load an unpublished working-tree catalog while adding an agent.

Go module

Depend on v1.0.0 as under Install.

Example

Open does no network I/O. Catalogs resolve lazily on first use, once, under a guard. Safe for concurrent use.

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/p3bot/agentdex"
)

func main() {
	ctx := context.Background()

	idx, err := agentdex.Open()
	if err != nil {
		log.Fatal(err)
	}

	res, err := idx.Agents.List(ctx, agentdex.AgentQuery{
		Enrich: agentdex.EnrichCount,
	})
	if err != nil {
		log.Fatal(err)
	}
	for _, w := range res.Warnings {
		fmt.Fprintln(os.Stderr, "warning:", w.Msg)
	}
	for _, a := range res.Items {
		fmt.Printf("%-14s installed=%t models=%d\n", a.ID, a.Detection.Found, a.ModelCount)
	}
}

type Index struct {
	Agents    AgentService
	Providers ProviderService
	Models    ModelService
}

Each service has List → Result[T] (items + warnings) and Get (exact). Detection is on Agent.Detection, not a top-level verb. Cache ops on Index: Refresh, CatalogInfo, CatalogStale, ModelsStale.

Options

Common options for Open (full list in package docs):

Option Role
WithCatalogDir Local CUE module (no network; never stale)
WithCatalogModule Override registry module path (exclusive with dir)
WithCacheDir Catalog + models.dev cache directory
WithWorkingDir Base for relative local paths
WithLookPath / WithSearchDirs / WithBinPaths Binary discovery
WithEnvLookup Env for path expansion and provider-env presence only
WithModelsURL / WithModelsTTL / WithCatalogTTL Sources and TTLs
WithHTTPClient / WithLogger HTTP and structured logging (silent by default)
Agents
res, err := idx.Agents.List(ctx, agentdex.AgentQuery{
	Installed: true,
	Providers: []string{"openai"}, // enrichment set for agnostic rows
	Enrich:    agentdex.EnrichNone,
})

detail, err := idx.Agents.Get(ctx, "claude-code", agentdex.AgentGetQuery{
	Enrich: agentdex.EnrichFull,
})
// detail.Detection.Config, detail.Detection.Skills, detail.Coverage, …

Enrich is the demand axis (each level is a superset). Installation does not gate enrichment.

Level Attaches
EnrichNone Catalog + detection. Get never contacts models.dev; List only to validate a non-empty Providers filter
EnrichProviders Resolved provider set
EnrichCount Provider-env presence, model count, coverage on Get
EnrichFull Full models list

Agent.Enrichment records applied, not-requested, not-applicable (agnostic with no providers), or degraded.

Detection always resolves config and skills paths whether or not the binary is installed. Found gates only BinaryPath and Version.

Skills are classified per scope (global, local): agents (shared .agents roots), native (product tree), alternatives (priority order). Primary is derived: agents, else native, else alternatives[0]. Full layout on Detection.Skills (path + exists per role). Zero SkillsPaths means no skills concept.

Agnostic agents have no home provider. Supply models.dev ids via Providers on the query (CLI: --provider). Home-provider agents reject an explicit set (ErrProvidersNotAllowed).

Providers
pres, err := idx.Providers.List(ctx, agentdex.ProviderQuery{Filter: "anthropic"})
p, err := idx.Providers.Get(ctx, "anthropic")
// p.Env, p.EnvPresent, len(p.Models)

From models.dev: id, name, API-key env names, and whether those variables are set (presence only).

Models
mres, err := idx.Models.List(ctx, agentdex.ModelQuery{
	Scope: agentdex.ModelScope{Providers: []string{"anthropic"}},
})
// Scope.Agent: "claude-code" uses that agent's providers; empty scope = all providers

m, err := idx.Models.Get(ctx, "anthropic/claude-sonnet-4-5")

Composite id is provider-id/model-id (split on the first slash). Agnostic agent scope without providers → ErrProvidersRequired.

Refresh and staleness
refreshed, err := idx.Refresh(ctx, agentdex.TargetAll) // TargetCatalog, TargetModels
info, err := idx.CatalogInfo(ctx)
stale, err := idx.CatalogStale(ctx)
mstale, err := idx.ModelsStale(ctx)

WithCatalogDir has nothing to re-resolve (not refreshed, no error).

Errors and warnings

Match with errors.Is. Common sentinels:

Sentinel Meaning
ErrCatalogUnavailable Cold offline, no prior catalog resolution
ErrCatalogInvalid Schema evaluation failed
ErrModelsUnavailable models.dev down on Providers/Models (agent ops degrade)
ErrModelsSchema Unrecognised models.dev shape (alias of modelsdev.ErrModelsSchema)
ErrAgentUnknown / ErrNotFound Unknown agent, provider, or model
ErrUnknownProvider Caller provider id not in models.dev
ErrProvidersRequired / ErrProvidersNotAllowed Agnostic vs home-provider provider-set rules
ErrMalformedModelID Model id with no /

Warnings carry Kind (branch) and Msg (emit verbatim). Valid on success and error returns; read Items only when err == nil.

Full list and types: pkg.go.dev/github.com/p3bot/agentdex@v1.0.0.

models.dev client package

Models.dev only (no agent index):

import "github.com/p3bot/agentdex/modelsdev"

Fetches catalog.json, merges provider and agnostic maps, checks gross schema drift, caches with stale-on-failure. Imports no agentdex internals. Docs: pkg.go.dev/github.com/p3bot/agentdex/modelsdev@v1.0.0.

Catalog and caching

Module Path Role
Go github.com/p3bot/agentdex Library and CLI
CUE github.com/p3bot/agentdex/catalog@v1 #KnownAgent schema + agent data

Published independently. The Go build ignores catalog/. The CUE module ships its own schema.cue; the loader validates by evaluation. Fetch uses cuelang.org/go/mod/modconfig and honours CUE_REGISTRY and cue login (no agentdex-specific auth).

Caches live under $XDG_CACHE_HOME/agentdex/ (default TTL 24h): catalog version resolution over CUE's content cache, plus models.dev catalog.json.

  • Latest-version resolution needs network; a pinned module@version can be served offline from CUE's content cache.
  • After TTL expiry, failed re-resolution keeps the last version and reports stale (usable with a warning).
  • First run with no network and no prior resolution → ErrCatalogUnavailable (CLI exit 75). Accepted behaviour.
  • Unreachable models.dev: agent ops degrade; Providers / Models return ErrModelsUnavailable.

Force a refresh: agentdex refresh or Index.Refresh.

Platforms

  • Linux, macOS, and WSL (agents installed natively in WSL Linux).
  • No native Windows; no Windows-host agents via WSL PATH interop.
  • Pure Go (CGO_ENABLED=0).

Contributing

Adding an agent is a catalog edit, not a code change: research outside facts, edit catalog/agents.cue, cue vet, exercise with catalog.dir, publish a new catalog version. Workflow and schema: AGENTS.md. Skills matrix: docs/agents-skills-path-matrix.md.

Library and CLI changes: open an issue or pull request against this repository. Prefer the standard library and existing dependencies; keep the binary pure Go.

License

MPL-2.0.

Documentation

Overview

Package agentdex indexes three kinds of data and serves them through one coherent surface: the AI coding agents in a published catalog, the models.dev providers that power them, and the models those providers offer. It owns the outside of an agent — identity, location, paths, version, capability — and never reads an agent's internal configuration.

Open constructs an *Index with no network I/O; catalogs resolve lazily once under a guard. Options configure catalog source (registry module or local WithCatalogDir), caches, detection, and boundary inputs (env lookup, WithLookPath, working dir). 

idx, err := agentdex.Open()
if err != nil { return err }
res, err := idx.Agents.List(ctx, agentdex.AgentQuery{Enrich: agentdex.EnrichCount})

Index exposes Agents, Providers, and Models, each with List and Get, plus Refresh and catalog/models staleness helpers. Detection is a property of an agent, not a top-level verb.

Enrich is the demand axis for agent operations (each level a superset):

  • EnrichNone: catalog and detection only. Get never contacts models.dev; List does so only to validate a non-empty Providers filter.
  • EnrichProviders: resolved provider set (offline for home-provider; validates caller ids for agnostic).
  • EnrichCount: ProviderEnv, ModelCount, and coverage on Agents.Get.
  • EnrichFull: full Models list on the same fetch as EnrichCount.

Installation does not gate enrichment. EnrichmentState records applied, not-requested, not-applicable (agnostic with no providers), or degraded.

Warnings carry Kind (branch) and Msg (emit verbatim) and are valid on the error return. Match errors with errors.Is against this package's sentinels; ErrModelsSchema aliases modelsdev.ErrModelsSchema. Adding an agent is a catalog edit: one generic detection path walks every entry.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrCatalogUnavailable is cold-offline with no fallback. Never raised under WithCatalogDir.
	ErrCatalogUnavailable = errors.New("agentdex catalog unavailable")

	// ErrCatalogInvalid is a module that loaded but failed schema evaluation (data, not network).
	ErrCatalogInvalid = errors.New("agentdex catalog invalid")

	// ErrModelsUnavailable is a non-schema models.dev fetch failure on Providers/Models.
	// Agent operations degrade instead.
	ErrModelsUnavailable = errors.New("models.dev unavailable")

	// ErrModelsSchema is the same value as modelsdev.ErrModelsSchema.
	ErrModelsSchema = modelsdev.ErrModelsSchema

	// ErrAgentUnknown is an agent id absent from the catalog.
	ErrAgentUnknown = errors.New("unknown agent id")

	// ErrUnknownProvider is a caller provider id models.dev does not know.
	ErrUnknownProvider = errors.New("unknown provider id")

	// ErrProvidersRequired is a model listing scoped to an agnostic agent with no providers.
	ErrProvidersRequired = errors.New("providers required for agnostic agent")

	// ErrProvidersNotAllowed is a home-provider agent given an explicit provider set.
	ErrProvidersNotAllowed = errors.New("providers not allowed for home-provider agent")

	// ErrMalformedModelID is a model composite with no "/".
	ErrMalformedModelID = errors.New("malformed model id")

	// ErrNotFound is a provider or model exact-get miss.
	ErrNotFound = errors.New("not found")
)

Exported sentinels for errors.Is. Detail rides the wrapping message (library- owned). ErrModelsSchema aliases modelsdev.ErrModelsSchema (same value).

Functions

This section is empty.

Types

type Agent 

type Agent struct {
	KnownAgent
	Detection         Detection
	ResolvedProviders []string
	ProviderEnv       map[string]bool // API-key env -> present; nil when models.dev not consulted
	Enrichment        EnrichmentState
	ModelCount        int     // meaningful when Enrichment == EnrichmentApplied
	Models            []Model // EnrichFull only; newest release first
}

Agent is catalog facts joined with detection and, from EnrichProviders upward, the resolved provider set and models.dev data. ResolvedProviders is empty below EnrichProviders and when an agnostic agent has no set.

type AgentDetail 

type AgentDetail struct {
	Agent
	Coverage ProviderCoverage
	Warnings []Warning
}

AgentDetail is Agents.Get: Agent plus coverage verdict and this fetch's warnings.

type AgentGetQuery 

type AgentGetQuery struct {
	Providers []string
	Enrich    Enrich
}

AgentGetQuery selects enrichment level and the agnostic provider set for Agents.Get.

type AgentQuery 

type AgentQuery struct {
	Filter    string
	Installed bool
	Providers []string
	Enrich    Enrich
}

AgentQuery narrows and enriches an Agents.List. Providers is the listing-wide set for agnostic rows, validated at the boundary.

type AgentService 

type AgentService struct {
	// contains filtered or unexported fields
}

AgentService browses and fetches agents joined with detection and enrichment.

func (AgentService) Get 

func (s AgentService) Get(ctx context.Context, id string, q AgentGetQuery) (AgentDetail, error)

Get returns detection detail for one agent, selected exactly by its catalog id. Coverage verdicts and not-installed or agnostic-without-providers are data plus warnings, never errors; warnings also ride the error return.

func (AgentService) List 

func (s AgentService) List(ctx context.Context, q AgentQuery) (Result[Agent], error)

List browses the catalog with local detection and, from EnrichProviders upward, the resolved provider set and models.dev enrichment. Detection fans out concurrently; no per-agent coverage is probed. Providers is validated once at the boundary at every level; an unknown id fails the whole listing.

type CatalogInfo 

type CatalogInfo struct {
	Source  CatalogSource
	Dir     string // set when Source is CatalogSourceDir
	Module  string // major-line path when Source is CatalogSourceRegistry
	Version string // resolved version when Source is CatalogSourceRegistry
	Stale   bool
}

CatalogInfo is the identity of the loaded agent catalog. A directory source has no version and is never stale.

type CatalogSource 

type CatalogSource int

CatalogSource identifies where the agent catalog was loaded from. 

const (
	// CatalogSourceRegistry is the CUE Central Registry (or CUE_REGISTRY).
	CatalogSourceRegistry CatalogSource = iota
	// CatalogSourceDir is a local CUE module directory from WithCatalogDir.
	CatalogSourceDir
)

func (CatalogSource) String 

func (s CatalogSource) String() string

String returns the constant name for known sources, or CatalogSource(n) for others.

type CoverageStatus 

type CoverageStatus int

CoverageStatus is the verdict of probing one agent's catalog provider set against models.dev. Zero is CoverageNotProbed; other values are probe results. 

const (
	// CoverageNotProbed means no models.dev contact, so no verdict.
	CoverageNotProbed CoverageStatus = iota
	CoverageAllPresent
	CoverageSomePresent
	CoverageNonePresent
	CoverageUnreachable
	CoverageSchemaDrift
)

func (CoverageStatus) String 

func (s CoverageStatus) String() string

String returns the constant name for known statuses, or CoverageStatus(n) for others.

type Detection 

type Detection struct {
	Found      bool
	BinaryPath string
	Version    string
	Config     ResolvedPaths
	Skills     SkillsPaths
}

Detection is what locating an agent found on this machine. Found gates only BinaryPath and Version; paths resolve the same whether or not the binary is installed.

type Enrich 

type Enrich int

Enrich selects how much provider and models.dev data an agent operation attaches. Each level is a superset of the one below. 

const (
	// EnrichNone is catalog and detection only. Get never contacts models.dev; List
	// still validates a non-empty Providers filter against it at every level.
	EnrichNone Enrich = iota
	// EnrichProviders adds the resolved provider set only (offline for home-provider;
	// validates caller ids for agnostic).
	EnrichProviders
	// EnrichCount adds ProviderEnv and ModelCount (and coverage on Agents.Get).
	EnrichCount
	// EnrichFull adds the Models list on the same fetch as EnrichCount.
	EnrichFull
)

func (Enrich) String 

func (e Enrich) String() string

String returns the constant name for known levels, or Enrich(n) for others.

type EnrichmentState 

type EnrichmentState int

EnrichmentState records the outcome of enrichment on a returned Agent. 

const (
	// EnrichmentNotRequested means Enrich was EnrichNone.
	EnrichmentNotRequested EnrichmentState = iota
	// EnrichmentApplied means the requested level was satisfied in full.
	EnrichmentApplied
	// EnrichmentNotApplicable is agnostic with no providers: outside facts only,
	// distinct from a real empty result.
	EnrichmentNotApplicable
	// EnrichmentDegraded means models.dev could not fill the level, so ModelCount is
	// not a true zero. Fault rides a List warning or Get coverage verdict.
	EnrichmentDegraded
)

func (EnrichmentState) String 

func (s EnrichmentState) String() string

String returns the constant name for known states, or EnrichmentState(n) for others.

type Index 

type Index struct {
	Agents    AgentService
	Providers ProviderService
	Models    ModelService
	// contains filtered or unexported fields
}

Index is the entry point and facade returned by Open. Safe for concurrent use: lazy catalog/models.dev resolution and Refresh publish under guards.

func Open 

func Open(opts ...Option) (*Index, error)

Open constructs an *Index over the configured catalog source and models.dev client. No network I/O and no context: both catalogs resolve lazily once under the first needing operation's context. Safe for concurrent use. WithCatalogDir and WithCatalogModule are mutually exclusive.

func (*Index) CatalogInfo 

func (x *Index) CatalogInfo(ctx context.Context) (CatalogInfo, error)

CatalogInfo returns the loaded agent catalog's identity. Lazy like other catalog ops: cold-offline first call is ErrCatalogUnavailable, not empty.

func (*Index) CatalogStale 

func (x *Index) CatalogStale(ctx context.Context) (bool, error)

CatalogStale is CatalogInfo(ctx).Stale. WithCatalogDir is never stale.

func (*Index) ModelsStale 

func (x *Index) ModelsStale(ctx context.Context) (bool, error)

ModelsStale reports a models.dev stale-cache fallback. Lazy load; cold-offline with nothing cached is ErrModelsUnavailable, not a misleading false.

func (*Index) Refresh 

func (x *Index) Refresh(ctx context.Context, t Target) (Refreshed, error)

Refresh forces re-resolution or refetch past caches and publishes the result. TargetAll runs catalog then models.dev and stops at the first failure; Refreshed names only targets that completed. Failed targets leave prior state untouched. WithCatalogDir has nothing to re-resolve (not-refreshed, no error).

type KnownAgent 

type KnownAgent struct {
	ID               string
	Name             string
	Bin              string
	Description      string
	Homepage         string
	CatalogProviders []string
	Agnostic         bool
}

KnownAgent is one catalog entry as identity and capability (no resolved paths). ID is the catalog map key. CatalogProviders is empty when Agnostic is true.

type Model 

type Model struct {
	modelsdev.Model
	Provider    string `json:"provider"`
	CanonicalID string `json:"canonical_id,omitempty"`
}

Model is a models.dev model with its provider and optional agnostic-catalog key. Every surface returns this type so a short id is never detached from its provider.

type ModelQuery 

type ModelQuery struct {
	Scope  ModelScope
	Filter string
}

ModelQuery scopes and narrows a Models.List.

type ModelScope 

type ModelScope struct {
	Agent     string
	Providers []string
}

ModelScope selects the provider set a model listing spans. Providers is also the enrichment set for an agnostic Agent.

type ModelService 

type ModelService struct {
	// contains filtered or unexported fields
}

ModelService browses and fetches models across models.dev providers.

func (ModelService) Get 

func (s ModelService) Get(ctx context.Context, composite string) (Model, error)

Get returns one model by composite provider-id/model-id. Splits on the first slash only (model key may contain slashes). No agent catalog, no warnings channel.

func (ModelService) List 

func (s ModelService) List(ctx context.Context, q ModelQuery) (Result[Model], error)

List browses models across the scoped providers, newest release first. Empty scope spans every models.dev provider. Each Model carries its provider and optional agnostic-map canonical id. Stale warnings ride the error path too.

type Option 

type Option func(*options)

Option configures Open. Nondeterministic inputs that shape reported values enter here (except process cache dir and clock). PATH search via WithLookPath.

func WithBinPaths 

func WithBinPaths(m map[string]string) Option

WithBinPaths overrides agents' binary paths by id (filesystem path, not PATH- resolved; relative roots at working directory; used for the version exec).

func WithCacheDir 

func WithCacheDir(dir string) Option

WithCacheDir sets the catalog resolution and models.dev cache directory. The clock stays on the process.

func WithCatalogDir 

func WithCatalogDir(dir string) Option

WithCatalogDir evaluates a local CUE module (never stale, no network). Mutually exclusive with WithCatalogModule; schema reject is ErrCatalogInvalid.

func WithCatalogModule 

func WithCatalogModule(path string) Option

WithCatalogModule overrides the registry catalog module path. Mutually exclusive with WithCatalogDir.

func WithCatalogTTL 

func WithCatalogTTL(d time.Duration) Option

WithCatalogTTL sets the catalog version-resolution cache TTL. Inert under WithCatalogDir.

func WithEnvLookup 

func WithEnvLookup(fn func(string) (string, bool)) Option

WithEnvLookup supplies env for provider-env presence and path expansion ($VAR, ~). Default os.LookupEnv. Only presence is taken from a variable, never its value.

func WithHTTPClient 

func WithHTTPClient(hc *http.Client) Option

WithHTTPClient overrides the HTTP client models.dev is fetched with.

func WithLogger 

func WithLogger(l *slog.Logger) Option

WithLogger threads a structured logger through decision points. Default is discard so the library is silent unless a caller opts in.

func WithLookPath 

func WithLookPath(fn func(string) (string, error)) Option

WithLookPath supplies PATH search for agent binaries (default exec.LookPath). Non-executable or failed hits fall through to WithSearchDirs. Inject a closed or fixture-scoped function so host PATH never leaks into detection.

func WithModelsTTL 

func WithModelsTTL(d time.Duration) Option

WithModelsTTL sets the models.dev cache TTL.

func WithModelsURL 

func WithModelsURL(url string) Option

WithModelsURL overrides the models.dev catalog source URL.

func WithSearchDirs 

func WithSearchDirs(dirs ...string) Option

WithSearchDirs adds binary search locations consulted after PATH.

func WithWorkingDir 

func WithWorkingDir(dir string) Option

WithWorkingDir sets the base for relative local config, skills, or binary paths. Default os.Getwd.

type PathEntry 

type PathEntry struct {
	Path   string
	Exists bool
}

PathEntry is one expanded catalog path with on-disk existence. Path is "" when that role is unsupported for the agent/scope.

type Provider 

type Provider struct {
	modelsdev.Provider
	EnvPresent map[string]bool
}

Provider is a models.dev provider with API-key env presence.

type ProviderCoverage 

type ProviderCoverage struct {
	Present []string
	Absent  []string
	Status  CoverageStatus
	// Err wraps the models.dev fault for Unreachable/SchemaDrift so errors.Is works.
	Err error
}

ProviderCoverage is per-provider models.dev coverage of one agent's set, as data.

type ProviderQuery 

type ProviderQuery struct {
	Filter string
}

ProviderQuery narrows a Providers.List by case-insensitive id/name substring.

type ProviderService 

type ProviderService struct {
	// contains filtered or unexported fields
}

ProviderService browses and fetches models.dev providers.

func (ProviderService) Get 

func (s ProviderService) Get(ctx context.Context, id string) (Provider, error)

Get returns one models.dev provider by id with API-key env presence. Unknown id is ErrNotFound. Loads no agent catalog (no warnings channel).

func (ProviderService) List 

func (s ProviderService) List(ctx context.Context, q ProviderQuery) (Result[Provider], error)

List browses models.dev providers by id order, optionally filtered. Loads no agent catalog. Stale fallback raises WarnModelsStale; outage is ErrModelsUnavailable; schema drift propagates modelsdev.ErrModelsSchema.

type Refreshed 

type Refreshed struct {
	Catalog bool
	Models  bool
}

Refreshed reports which targets a Refresh actually re-resolved or refetched.

type ResolvedPaths 

type ResolvedPaths struct {
	Global       string
	GlobalExists bool
	Local        string
	LocalExists  bool
}

ResolvedPaths is a catalog directory pair after expansion, with existence per scope. Local is "" when the catalog defines no local scope.

type Result 

type Result[T any] struct {
	Items    []T
	Warnings []Warning
}

Result is the symmetric return of every List: ordered items and warnings. Warnings are valid on the error return; read Items only when err is nil.

type SkillsPaths 

type SkillsPaths struct {
	Global SkillsScope
	Local  SkillsScope
}

SkillsPaths is resolved skills by scope. Zero means the agent has no skills concept.

type SkillsScope 

type SkillsScope struct {
	Agents       PathEntry
	Native       PathEntry
	Alternatives []PathEntry
	Primary      PathEntry
}

SkillsScope is one scope's classified skill roots after expansion. Primary: agents else native else Alternatives[0]. Alternatives is priority order.

type Target 

type Target int

Target selects which caches a Refresh forces. 

const (
	TargetCatalog Target = iota
	TargetModels
	TargetAll
)

func (Target) String 

func (t Target) String() string

String returns the constant name for known targets, or Target(n) for others.

type Warning 

type Warning struct {
	Kind WarningKind
	Msg  string
}

Warning is Kind for branching and Msg for verbatim emission.

type WarningKind 

type WarningKind int

WarningKind classifies a non-fatal condition. Same kind may carry different Msg wording per operation; branch on Kind, emit Msg verbatim. 

const (
	WarnStaleCatalog WarningKind = iota
	WarnModelsUnreachable
	WarnModelsSchemaDrift
	WarnSomeProvidersAbsent
	WarnNotInstalled
	// WarnProvidersRequired is guidance: agnostic agent reported without providers.
	WarnProvidersRequired
	// WarnModelsStale: stale cache fallback after failed refetch; only when consulted.
	WarnModelsStale
)

func (WarningKind) String 

func (k WarningKind) String() string

String returns the constant name for known kinds, or WarningKind(n) for others.

Source Files

View all Source files

Directories

Path Synopsis
cmd
agentdex command
Command agentdex is the thin CLI over the agentdex detection library.
 Command agentdex is the thin CLI over the agentdex detection library.
internal
catalog
Package catalog fetches the agentdex agent catalog from the CUE Central Registry, validates it by evaluating the fetched module against its bundled schema, caches the resolved module version, and decodes the catalog into an internal representation.
 Package catalog fetches the agentdex agent catalog from the CUE Central Registry, validates it by evaluating the fetched module against its bundled schema, caches the resolved module version, and decodes the catalog into an internal representation.
catalogtest
Package catalogtest provides a stub registry and fixture helpers shared by the catalog loader tests and the root-package mapping tests.
 Package catalogtest provides a stub registry and fixture helpers shared by the catalog loader tests and the root-package mapping tests.
cli
Package cli is the agentdex command-line interface: a thin wrapper over the agentdex library and the modelsdev client.
 Package cli is the agentdex command-line interface: a thin wrapper over the agentdex library and the modelsdev client.
config
Package config loads and validates the agentdex user configuration (config.cue), resolves the XDG paths it lives under, resolves the per-cache TTLs, and maps the configuration together with the global flags into the agentdex library options and the modelsdev client options.
 Package config loads and validates the agentdex user configuration (config.cue), resolves the XDG paths it lives under, resolves the per-cache TTLs, and maps the configuration together with the global flags into the agentdex library options and the modelsdev client options.
modelsdevtest
Package modelsdevtest provides shared models.dev test doubles: fixture providers and the httptest servers that serve them, so library and CLI tests exercise the same deterministic, network-free models.dev.
 Package modelsdevtest provides shared models.dev test doubles: fixture providers and the httptest servers that serve them, so library and CLI tests exercise the same deterministic, network-free models.dev.
tui
Package tui renders agentdex's human-facing text output: NO_COLOR-aware colour styling and aligned tables.
 Package tui renders agentdex's human-facing text output: NO_COLOR-aware colour styling and aligned tables.
Package modelsdev is a reusable client for models.dev, the community database of model specifications, pricing, and capabilities.
 Package modelsdev is a reusable client for models.dev, the community database of model specifications, pricing, and capabilities.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.