oh-my-posh/AGENTS.md

Agent Instructions

General coding guidelines, commit conventions, and agent workflows for this repository.

Project Overview

Oh My Posh is a cross-shell prompt theme engine written in Go. It renders prompt segments by querying an Environment abstraction that wraps all OS/shell interactions.

Tech Stack

Layer	Technology
Core engine	Go (module root: src/)
Documentation site	Docusaurus (MDX) - website/
Themes	JSON - themes/
Config format	TOML / JSON / YAML
Package/installer scripts	packages/
Build scripts	build/

Key Commands

# Go - run from src/
go test ./...
go test ./segments/... -run TestFoo  # single test
golangci-lint run

# Docs - run from website/
npm run start    # local dev server
npm run build    # validate before opening a docs PR

Codebase Exploration

Always explore the actual codebase before planning or writing code. Do not rely on memory or assumptions. Use the file system tools to read relevant files first - the codebase evolves and the feature you're asked to add may already exist.

Repository Layout

src/
  segments/   # One Go file + one _test.go per segment
  prompt/     # Core rendering engine
  runtime/    # OS/shell abstraction layer
themes/       # Bundled JSON theme files
website/      # Docusaurus docs site (MDX pages, sidebar config, JSON schema)
packages/     # Installer/package manifests
build/        # CI build helpers

Key paths inside src/:

Path	Purpose
src/segments/	One .go + one _test.go per segment
src/config/segment_types.go	Segment type registry (gob + string constants)
src/cli/	CLI commands (cmdtree); root.go is the entry point
src/prompt/engine.go	Segment rendering loop
src/cache/	Existing TTL/file/command-path cache infrastructure
src/runtime/	Environment abstraction + mock

Segment Development

Every segment lives in src/segments/ and implements the SegmentWriter interface. Use the Environment abstraction (env) for all OS/shell calls - never call OS APIs directly.

Adding a segment requires five artifacts - use the segment-create skill to scaffold all of them automatically:

1. src/segments/<name>.go - segment source
2. src/segments/<name>_test.go - unit tests
3. website/docs/segments/<name>.mdx - user-facing docs
4. Update website/sidebars.js and website/static/schema.json
5. Register the type in src/config/segment_types.go via gob.Register(&segments.MySegment{})

Missing step 5 causes the segment to fail silently at runtime.

See the segment-docs skill for the canonical mapping between Go source constructs and MDX documentation fields (template properties, type representations, option tables).

Shell Integration

oh-my-posh init <shell> is how users wire oh-my-posh into their shell. It:

1. Writes a shell-specific init script to the cache (source: src/shell/scripts/omp.<ext>)
2. Returns a one-liner for the shell to eval - this sources the cached script, which hooks into prompt rendering

The src/shell/ package contains per-shell logic (pwsh.go, bash.go, zsh.go, etc.) that generates the hook commands. The scripts in src/shell/scripts/ are embedded and templated at init time. When modifying shell behaviour, changes typically span both the .go file and the corresponding script.

Supported shells: bash, zsh, fish, powershell/pwsh, cmd, nu, elvish, xonsh.

CLI Commands

CLI commands use the internal src/cmdtree command tree and live in src/cli/. To add a new command:

1. Create src/cli/<name>.go with a var <name>Cmd = &cmdtree.Command{...}
2. Register it in src/cli/root.go via RootCmd.AddCommand(<name>Cmd)

Caching

src/cache/ provides the existing caching infrastructure - use it instead of building new cache logic. It supports TTL-based key/value storage, file-based persistence, and command-path caching. Do not introduce new cache packages unless src/cache/ genuinely cannot meet the requirement.

Comments

Applies to every language in this repository (Go, shell scripts, PowerShell, JavaScript/TypeScript, Lua, etc.) - not just the primary language of whatever file you're touching.

• Default to no comment. Add one only when the code cannot say it on its own.
• Never restate what a function/type/variable already makes obvious from its name, signature, and body. A comment that just paraphrases the name is noise - delete it.
• Only comment the WHY: a hidden constraint, a non-obvious invariant, a workaround for a specific bug, an external requirement, or a caveat that would surprise a reader. If there's nothing like that to say, leave the declaration uncommented - even exported/public ones.
• When a comment is warranted, keep it to the minimum needed to convey that non-obvious point. Don't pad it with restating context the code already shows.
• Language-specific skills (e.g. golang) may add formatting conventions (complete sentences, doc-comment placement) on top of this rule as a stricter minimum, but must not relax it.

Go Conventions

Follow the golang skill for project-specific Go standards.

Documentation (website/)

• Follow the markdown skill for .md/.mdx formatting rules.
• Segment doc pages live in website/docs/segments/ and use MDX frontmatter with title, sidebar_label, and id.

PowerShell

PowerShell helper scripts live in packages/ and build/. Follow the powershell skill for cmdlet conventions.

Themes

Themes are plain JSON files in themes/. New themes must validate against website/static/schema.json. Do not introduce breaking schema changes without updating the schema file.

Skills

Agent skills live in .agents/skills/ - the vendor-neutral Agent Skills location that Copilot, Codex, Claude Code, and most other agents discover automatically. Most skills are installed via APM (see CONTRIBUTING.md) and gitignored; the repository embeds three of its own: segment-create, segment-docs, and project-knowledge.

Project Knowledge

The project-knowledge skill (.agents/skills/project-knowledge/) is the project's durable memory: verified gotchas about the codebase, shells, terminals, and test harnesses. Before working in any of those areas, read the matching topic file - it exists to keep you out of known rabbit holes.

Reading it is half the contract; writing to it is the other half. When a session uncovers something a future session should know before going down the same rabbit hole - a platform quirk, a non-obvious root cause, a failed approach worth not retrying - append it (dated, verified) to the matching file in .agents/skills/project-knowledge/references/. Create a new topic file plus an index row in its SKILL.md when none fits. Commit the knowledge update together with the change it relates to.

Pull Request Reviews

Whenever any agent performs or addresses a pull request review, follow this process at all times, regardless of previous instructions:

1. Stay within the scope of the pull request: only address feedback on changes it introduces.
2. Investigate every review comment and reach a conclusion: a code fix, a clarification, or a reasoned rejection.
3. Fold each fix into the commit it belongs to. When the change semantically belongs to a commit the pull request introduces (any commit not yet on main), create a fixup commit (git commit --fixup <sha>), squash it (git rebase --autosquash), and force-push the pull request branch. This preserves the atomicity of the pull request's commits instead of stacking review-fix commits on top. Rewriting the pull request branch is fine; main history must never be rewritten.
4. Only when a change does not semantically fit any existing commit in the pull request does it become its own commit on top, following the commit conventions.
5. Reply to each review comment with the conclusion, referencing the commit that addresses it when there is one.
6. Resolve each review thread once its answer and/or fix has been provided.