cursor

package
v0.1.1 Latest Latest
Warning

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

 Go to latest Published: Jan 22, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package cursor provides Cursor CLI configuration management.

Package cursor provides Cursor CLI configuration management.

Package cursor provides Cursor CLI configuration management.

Index

Constants

View Source 
const (
	SessionStatusActive    = "active"
	SessionStatusSuspended = "suspended"
	SessionStatusCompleted = "completed"
)

SessionStatus constants.

Variables

View Source 
var SupportedModels = []string{
	"auto",
	"opus-4.5-thinking",
	"opus-4.5",
	"sonnet-4.5",
	"sonnet-4.5-thinking",
	"gpt-5.2",
	"gpt-5.2-high",
	"gpt-5.1-codex-max",
	"gemini-3-pro",
	"gemini-3-flash",
	"grok",
}

SupportedModels returns the list of supported models. These are the models available via cursor-agent.

Functions

func AddMCPServer 

func AddMCPServer(workDir, name string, server MCPServer) error

AddMCPServer adds or updates an MCP server in the workspace configuration.

func Available 

func Available() bool

Available checks if cursor-agent is available in PATH.

func CaptureSessionID 

func CaptureSessionID(output string) string

CaptureSessionID attempts to capture the session ID from cursor-agent output. This is called from the stop hook to record the session for potential resume.

cursor-agent outputs session info in various ways: - In JSON output mode: {"chat_id": "..."} - In text mode: Look for patterns like "Session: abc123" or "Chat ID: abc123"

func CleanOrphanClaudeConfig 

func CleanOrphanClaudeConfig(workDir string) (bool, error)

CleanOrphanClaudeConfig removes any orphaned Claude-specific configuration files. Returns true if any files were cleaned, false otherwise. This is a no-op in the current implementation as we've moved to multi-model orchestration.

func CreateChat 

func CreateChat(workDir string) (string, error)

CreateChat creates a new cursor-agent chat and returns its ID. This uses 'cursor-agent create-chat' if available.

func EnsureGasTownMCPServers 

func EnsureGasTownMCPServers(workDir string) error

EnsureGasTownMCPServers ensures Gas Town MCP servers are configured. Currently a no-op as Gas Town does not yet have an MCP server.

func EnsureHooks 

func EnsureHooks(workDir string) error

EnsureHooks ensures Gas Town hooks are installed in the workspace. This creates .cursor/hooks.json and .cursor/hooks/ directory with hook scripts.

func EnsureSettings 

func EnsureSettings(workDir string, roleType RoleType) error

EnsureSettings ensures .cursor/rules directory exists with Gas Town rules, and installs Gas Town hooks for Cursor CLI. For worktrees, we use sparse checkout to exclude source repo's .cursor/ directory, so our rules are the only ones Cursor sees.

func EnsureSettingsForRole 

func EnsureSettingsForRole(workDir, role string) error

EnsureSettingsForRole is a convenience function that combines RoleTypeFor and EnsureSettings.

func EnsureWorkspaceReady 

func EnsureWorkspaceReady(workDir, role string) error

EnsureWorkspaceReady ensures the workspace is ready for cursor-agent. This creates necessary directories and configuration files.

func GetLatestSession 

func GetLatestSession() (string, error)

GetLatestSession returns the most recent cursor-agent session.

func GetModelForRole 

func GetModelForRole(role string) string

GetModelForRole returns the recommended model for a Gas Town role. This implements the Council's role-model matrix.

func GetModelRationale 

func GetModelRationale(role string) string

GetModelRationale returns the reasoning for a role's model choice.

func GlobalMCPConfigPath 

func GlobalMCPConfigPath() (string, error)

GlobalMCPConfigPath returns the path to the global mcp.json. This is located at ~/.cursor/mcp.json for user-wide configuration.

func HooksInstalled 

func HooksInstalled(workDir string) bool

HooksInstalled checks if Gas Town hooks are installed in the workspace.

func IsValidModel 

func IsValidModel(model string) bool

IsValidModel checks if a model name is valid.

func ListCursorSessions 

func ListCursorSessions() ([]string, error)

ListCursorSessions runs 'cursor-agent ls' to list available sessions. Note: This may not work in non-TTY environments.

func ListMCPServers 

func ListMCPServers(workDir string) ([]string, error)

ListMCPServers returns a list of configured MCP server names.

func MCPConfigPath 

func MCPConfigPath(workDir string) string

MCPConfigPath returns the path to the workspace-level mcp.json. This is located at .cursor/mcp.json in the workspace root.

func ModelProvider 

func ModelProvider(model string) string

ModelProvider returns the provider for a given model.

func RemoveHooks 

func RemoveHooks(workDir string) error

RemoveHooks removes Gas Town hooks from the workspace.

func RemoveMCPServer 

func RemoveMCPServer(workDir, name string) error

RemoveMCPServer removes an MCP server from the workspace configuration.

func ResumeSession 

func ResumeSession(sessionID string, args ...string) []string

ResumeSession builds a command to resume a cursor-agent session.

func SaveMCPConfig 

func SaveMCPConfig(path string, config *MCPConfig) error

SaveMCPConfig writes an MCP configuration to the given path.

func Version 

func Version() (string, error)

Version returns the cursor-agent version.

Types

type Adapter 

type Adapter struct {
	// WorkDir is the workspace directory.
	WorkDir string

	// Model is the model to use (e.g., "sonnet-4.5", "gpt-5.2").
	Model string

	// ForceMode enables YOLO/force mode (-f flag).
	ForceMode bool

	// PrintMode enables non-interactive/print mode (-p flag).
	PrintMode bool

	// OutputFormat specifies output format ("text" or "json").
	OutputFormat string

	// SessionID is an optional session ID for resume.
	SessionID string

	// ApproveAll auto-approves MCP servers and other prompts.
	ApproveAll bool

	// AdditionalArgs are extra arguments to pass to cursor-agent.
	AdditionalArgs []string
}

Adapter translates Gas Town operations to Cursor CLI commands. This is the primary interface for interacting with cursor-agent.

func AdapterForRole 

func AdapterForRole(workDir, role string) *Adapter

AdapterForRole returns an adapter configured for a specific Gas Town role.

func DefaultAdapter 

func DefaultAdapter(workDir string) *Adapter

DefaultAdapter returns an adapter with sensible defaults for Gas Town.

func TranslateRuntimeConfig 

func TranslateRuntimeConfig(rc *config.RuntimeConfig, workDir string) *Adapter

TranslateRuntimeConfig converts a Gas Town RuntimeConfig to an Adapter.

func (*Adapter) BuildArgs 

func (a *Adapter) BuildArgs(prompt string) []string

BuildArgs builds the command-line arguments for cursor-agent.

func (*Adapter) BuildCommand 

func (a *Adapter) BuildCommand(prompt string) *exec.Cmd

BuildCommand builds the cursor-agent command with all configured options.

func (*Adapter) BuildCommandString 

func (a *Adapter) BuildCommandString(prompt string) string

BuildCommandString returns the full command as a string (for tmux SendKeys).

func (*Adapter) Run 

func (a *Adapter) Run(prompt string) (string, error)

Run executes cursor-agent and returns the output. For non-interactive use; use BuildCommand for interactive sessions.

func (*Adapter) RunJSON 

func (a *Adapter) RunJSON(prompt string) ([]byte, error)

RunJSON executes cursor-agent and returns JSON output.

type HookEntry 

type HookEntry struct {
	Command string `json:"command"`
}

HookEntry represents a single hook configuration

type HooksConfig 

type HooksConfig struct {
	Version int                    `json:"version"`
	Hooks   map[string][]HookEntry `json:"hooks"`
}

HooksConfig represents the structure of Cursor's hooks.json

type MCPAuth 

type MCPAuth struct {
	// ClientID is the OAuth 2.0 Client ID from the MCP provider.
	ClientID string `json:"CLIENT_ID,omitempty"`

	// ClientSecret is the OAuth 2.0 Client Secret (for confidential clients).
	ClientSecret string `json:"CLIENT_SECRET,omitempty"`

	// Scopes are the OAuth scopes to request.
	Scopes []string `json:"scopes,omitempty"`
}

MCPAuth contains OAuth configuration for remote MCP servers.

type MCPConfig 

type MCPConfig struct {
	// McpServers maps server names to their configurations.
	McpServers map[string]MCPServer `json:"mcpServers"`
}

MCPConfig represents the structure of a Cursor mcp.json file. See: https://cursor.com/docs/context/mcp

func LoadMCPConfig 

func LoadMCPConfig(path string) (*MCPConfig, error)

LoadMCPConfig loads an MCP configuration from the given path. Returns an empty config if the file doesn't exist.

func MergeMCPConfigs 

func MergeMCPConfigs(configs ...*MCPConfig) *MCPConfig

MergeMCPConfigs merges multiple MCP configurations. Later configs override earlier ones for servers with the same name.

type MCPServer 

type MCPServer struct {
	// Type indicates the server transport type: "stdio" for local commands.
	// If URL is set and Command is empty, the type is implied to be HTTP/SSE.
	Type string `json:"type,omitempty"`

	// URL is the endpoint URL for the MCP server (for HTTP-based servers).
	URL string `json:"url,omitempty"`

	// Command is the command to run for stdio-based MCP servers.
	Command string `json:"command,omitempty"`

	// Args are command-line arguments for stdio-based servers.
	Args []string `json:"args,omitempty"`

	// Env contains environment variables for the server process.
	// Supports interpolation: ${env:NAME}, ${workspaceFolder}, ${userHome}
	Env map[string]string `json:"env,omitempty"`

	// EnvFile is the path to an environment file to load additional variables.
	// Supports interpolation: ${workspaceFolder}/.env
	EnvFile string `json:"envFile,omitempty"`

	// Headers contains HTTP headers for HTTP-based servers.
	// Supports interpolation: ${env:MY_TOKEN}
	Headers map[string]string `json:"headers,omitempty"`

	// Auth contains OAuth configuration for remote servers.
	Auth *MCPAuth `json:"auth,omitempty"`
}

MCPServer represents an MCP server configuration. Supports both stdio (local command) and HTTP-based (remote URL) servers.

func GetMCPServer 

func GetMCPServer(workDir, name string) (*MCPServer, error)

GetMCPServer returns a specific MCP server configuration. Returns nil if the server doesn't exist.

func (*MCPServer) IsConfigured 

func (s *MCPServer) IsConfigured() bool

IsConfigured checks if the MCP server has minimum required configuration.

func (*MCPServer) MCPServerType 

func (s *MCPServer) MCPServerType() string

MCPServerType returns the type of an MCP server ("stdio" or "http").

type RoleType 

type RoleType string

RoleType indicates whether a role is autonomous or interactive. 

const (
	// Autonomous roles (polecat, witness, refinery) need initialization commands
	// at session start because they may be triggered externally.
	Autonomous RoleType = "autonomous"

	// Interactive roles (mayor, crew) wait for user input.
	Interactive RoleType = "interactive"
)

func RoleTypeFor 

func RoleTypeFor(role string) RoleType

RoleTypeFor returns the RoleType for a given role name.

type Session 

type Session struct {
	// ID is the unique chat/session identifier from cursor-agent.
	ID string `json:"id"`

	// WorkDir is the workspace directory where the session was created.
	WorkDir string `json:"work_dir"`

	// Role is the Gas Town role (mayor, polecat, witness, etc.).
	Role string `json:"role,omitempty"`

	// RigName is the rig this session belongs to (empty for town-level sessions).
	RigName string `json:"rig_name,omitempty"`

	// Model is the model used for this session.
	Model string `json:"model,omitempty"`

	// CreatedAt is when the session was created.
	CreatedAt time.Time `json:"created_at"`

	// LastActiveAt is the last time the session was active.
	LastActiveAt time.Time `json:"last_active_at"`

	// Status is the current session status (active, suspended, completed).
	Status string `json:"status"`
}

Session represents a Cursor CLI session.

func SessionFromEnv 

func SessionFromEnv(workDir, role, rigName string) *Session

SessionFromEnv creates a Session from environment variables. This is used during session startup to capture context.

func (*Session) MarkCompleted 

func (s *Session) MarkCompleted()

MarkCompleted marks the session as completed.

func (*Session) MarkSuspended 

func (s *Session) MarkSuspended()

MarkSuspended marks the session as suspended.

func (*Session) Touch 

func (s *Session) Touch()

Touch updates the LastActiveAt timestamp.

type SessionStore 

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

SessionStore manages session state persistence.

func NewSessionStore 

func NewSessionStore(dir string) (*SessionStore, error)

NewSessionStore creates a new session store. The store is backed by a JSON file in the given directory.

func (*SessionStore) CleanupStale 

func (s *SessionStore) CleanupStale(maxAge time.Duration) error

CleanupStale removes sessions older than the given duration.

func (*SessionStore) Delete 

func (s *SessionStore) Delete(id string) error

Delete removes a session.

func (*SessionStore) Get 

func (s *SessionStore) Get(id string) *Session

Get returns a session by ID.

func (*SessionStore) GetByRole 

func (s *SessionStore) GetByRole(role, rigName string) *Session

GetByRole returns the most recent active session for a role.

func (*SessionStore) List 

func (s *SessionStore) List() []*Session

List returns all sessions.

func (*SessionStore) ListActive 

func (s *SessionStore) ListActive() []*Session

ListActive returns all active sessions.

func (*SessionStore) Put 

func (s *SessionStore) Put(sess *Session) error

Put stores a session.

Source Files

View all Source files

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.