How to Add Support for a New AI Coding Agent to AgentsView

To add support for a new AI coding agent to AgentsView, implement the parser.Provider interface by declaring an AgentDef in internal/parser/types.go, creating a provider factory that handles discovery and parsing, and wiring it into the global factory list in internal/parser/provider.go.

AgentsView discovers, watches, and parses coding sessions by delegating to modular providers that implement the parser.Provider interface. Each provider acts as a bridge between the agent's storage format—whether JSONL files, SQLite databases, or proprietary formats—and AgentsView's unified session model. Adding support for a new AI coding agent requires implementing this provider contract following the architectural patterns established by existing agents like OpenCode and Gemini.

Step 1: Declare the Agent in the Registry

Open internal/parser/types.go and add a new constant to the AgentType enumeration, then append an AgentDef entry to the Registry slice.

First, define the type constant at the top of the file:

AgentMyAgent AgentType = "myagent"

Then add the agent definition to the Registry:

{
    Type:        AgentMyAgent,
    DisplayName: "MyAgent",
    EnvVar:      "MYAGENT_DIR",
    ConfigKey:   "myagent_dirs",
    DefaultDirs: []string{".myagent/sessions"},
    IDPrefix:    "myagent:",
    FileBased:   true,
    WatchSubdirs: []string{"sessions"},
},

The AgentDef struct tells AgentsView where to look for session files, which environment variables to check, and how to identify the agent's sessions via the IDPrefix.

Step 2: Create the Provider Factory

Create a new file at internal/parser/myagent_provider.go. This file implements the factory pattern used by OpenCode and Gemini providers. The factory must return a concrete type that satisfies the Provider interface.

Start with the factory struct and constructor:

package parser

import "context"

var _ Provider = (*myAgentProvider)(nil)

type myAgentProviderFactory struct {
    def AgentDef
}

func newMyAgentProviderFactory(def AgentDef) ProviderFactory {
    return myAgentProviderFactory{def: cloneAgentDef(def)}
}

func (f myAgentProviderFactory) Definition() AgentDef {
    return cloneAgentDef(f.def)
}

func (f myAgentProviderFactory) Capabilities() Capabilities {
    return myAgentProviderCapabilities()
}

func (f myAgentProviderFactory) NewProvider(cfg ProviderConfig) Provider {
    cfg = cfg.Clone()
    return &myAgentProvider{
        ProviderBase: ProviderBase{
            Def:    cloneAgentDef(f.def),
            Caps:   myAgentProviderCapabilities(),
            Config: cfg,
        },
        sources: newMyAgentSourceSet(cfg.Roots),
    }
}

The NewProvider method initializes the provider with a source set that handles filesystem-specific operations.

Step 3: Implement the Source Set

The provider delegates six core operations to a source set: Discover, WatchPlan, SourcesForChangedPath, FindSource, Fingerprint, and Parse. Create a myAgentSourceSet struct to manage these concerns.

Discovery

Implement Discover to walk the filesystem and locate session files. For JSONL-based agents, use the cleanJSONLRoots helper and walk directories looking for *.jsonl files:

type myAgentSourceSet struct {
    roots []string
}

func newMyAgentSourceSet(roots []string) myAgentSourceSet {
    return myAgentSourceSet{roots: cleanJSONLRoots(roots)}
}

func (s myAgentSourceSet) Discover(ctx context.Context) ([]SourceRef, error) {
    var srcs []SourceRef
    seen := map[string]struct{}{}
    
    for _, root := range s.roots {
        path := filepath.Join(root, "sessions")
        err := filepath.WalkDir(path, func(p string, d fs.DirEntry, err error) error {
            if err != nil || d.IsDir() || !strings.HasSuffix(p, ".jsonl") {
                return nil
            }
            if source, ok := s.sourceRef(root, p); ok {
                addJSONLSource(source, &srcs, seen)
            }
            return nil
        })
        if err != nil && ctx.Err() == nil {
            return nil, err
        }
    }
    sortJSONLSources(srcs)
    return srcs, nil
}

Watch Plan

The WatchPlan method tells the engine which directories to monitor for changes:

func (s myAgentSourceSet) WatchPlan(context.Context) (WatchPlan, error) {
    var roots []WatchRoot
    for _, r := range s.roots {
        roots = append(roots, WatchRoot{
            Path:         r,
            Recursive:    true,
            IncludeGlobs: []string{"*.jsonl"},
            DebounceKey:  string(AgentMyAgent) + ":watch:" + r,
        })
    }
    return WatchPlan{Roots: roots}, nil
}

Fingerprinting

Implement Fingerprint to detect when session files change by hashing their contents:

func (s myAgentSourceSet) Fingerprint(_ context.Context, src SourceRef) (SourceFingerprint, error) {
    path, ok := s.pathFromSource(src)
    if !ok {
        return SourceFingerprint{}, fmt.Errorf("myagent source path unavailable")
    }
    
    info, err := os.Stat(path)
    if err != nil {
        return SourceFingerprint{}, err
    }
    
    h := sha256.New()
    f, err := os.Open(path)
    if err != nil {
        return SourceFingerprint{}, err
    }
    defer f.Close()
    
    if _, err = io.Copy(h, f); err != nil {
        return SourceFingerprint{}, err
    }
    
    return SourceFingerprint{
        Key:     path,
        Size:    info.Size(),
        MTimeNS: info.ModTime().UnixNano(),
        Hash:    fmt.Sprintf("%x", h.Sum(nil)),
    }, nil
}

Parsing

The Parse method reads the agent's native format and converts it to AgentsView's canonical ParsedSession and ParsedMessage structs. Reference parseOpenCodeStorageFile or parseGeminiSession in the existing codebase for implementation patterns.

Step 4: Register the Factory in the Global List

Open internal/parser/provider.go and update the providerFactoryForDef function to include your new agent type in the switch statement:

case AgentMyAgent:
    return newMyAgentProviderFactory(def)

Because ProviderFactories() iterates over the Registry slice and calls providerFactoryForDef for each entry, your new provider will automatically appear in the CLI, sync engine, and UI once this case is added.

Step 5: Declare Capabilities

Capabilities tell the system which features your provider supports. Create a myAgentProviderCapabilities function that returns a Capabilities struct:

func myAgentProviderCapabilities() Capabilities {
    return Capabilities{
        Source: SourceCapabilities{
            DiscoverSources:      CapabilitySupported,
            WatchSources:         CapabilitySupported,
            ClassifyChangedPath:  CapabilitySupported,
            FindSource:           CapabilitySupported,
            CompositeFingerprint: CapabilitySupported,
            IncrementalAppend:    CapabilityNotApplicable,
            MultiSessionSource:   CapabilityNotApplicable,
        },
        Content: ContentCapabilities{
            FirstMessage:         CapabilitySupported,
            Cwd:                  CapabilitySupported,
            Relationships:        CapabilitySupported,
            Thinking:             CapabilitySupported,
            ToolCalls:            CapabilitySupported,
            PerMessageTokenUsage: CapabilitySupported,
            Model:                CapabilitySupported,
        },
    }
}

Set CapabilitySupported for features your agent implements and CapabilityNotApplicable for features that don't apply to your agent's storage model.

Step 6: Test and Verify

AgentsView includes a comprehensive test suite that validates discovery, fingerprinting, and parsing for each provider. After implementing your provider:

make test           # Run all Go tests including the new provider

make test-short     # Quick sanity check

Verify your agent appears in the provider list:

agentsview --list-agents

If you expose the agent in the UI, add localization entries to frontend/messages/en.json following the conventions described in AGENTS.md.

Summary

Adding a new AI coding agent to AgentsView requires implementing the provider interface with five key components:

• Registry entry – Define AgentType constant and AgentDef in internal/parser/types.go to specify discovery paths and naming.
• Provider factory – Create newMyAgentProviderFactory in a new file (e.g., myagent_provider.go) that returns a concrete Provider implementation.
• Source set – Implement Discover, WatchPlan, Fingerprint, and Parse methods to handle filesystem operations and parsing.
• Factory registration – Add a case to providerFactoryForDef in internal/parser/provider.go to wire the factory into the global list.
• Capabilities – Declare what features the provider supports via the Capabilities struct.

Once complete, AgentsView will automatically discover, watch, and parse sessions produced by your new AI coding agent.

Frequently Asked Questions

What interface must a new agent provider implement?

A new agent provider must implement the parser.Provider interface defined in the AgentsView codebase. This interface requires six methods: Discover, WatchPlan, SourcesForChangedPath, FindSource, Fingerprint, and Parse. According to the source code in internal/parser/provider.go, providers typically delegate these methods to a source set that handles filesystem-specific concerns.

Where do I register a new agent provider in AgentsView?

You register a new agent provider in two locations. First, add the AgentDef to the Registry slice in internal/parser/types.go. Second, add a case to the providerFactoryForDef function in internal/parser/provider.go that returns your factory function. The ProviderFactories() function automatically picks up any AgentDef that has a matching factory case.

How does AgentsView detect changes to agent session files?

AgentsView detects changes through the WatchPlan method of your source set, which returns a WatchPlan struct specifying which directories to monitor. The system uses the Fingerprint method to compute a SHA-256 hash of file contents combined with modification times, allowing it to detect when session files change and need re-parsing.

What capabilities should I declare for a file-based coding agent?

For a standard file-based agent using JSONL storage, declare CapabilitySupported for DiscoverSources, WatchSources, ClassifyChangedPath, FindSource, and CompositeFingerprint in the Source capabilities. In the Content capabilities, declare support for FirstMessage, Cwd, ToolCalls, Model, and other features your agent logs. Set IncrementalAppend and MultiSessionSource to CapabilityNotApplicable unless your agent supports multi-session files or streaming appends.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}