MoonshotAI / MoonshotAI/kimi-cli

[Feature Request] Support global ~/.kimi/AGENTS.md for multi-project shared conventions

Open
#2,152 4 comments 5 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
11.4k
Forks
1.3k
Avg merge
9h 47m
Merged PRs (30d)
2

Description

Problem

Currently AGENTS.md is only loaded from the current working directory. This creates significant friction for developers who maintain many projects in parallel.

My Pain Points
  1. Multiple projects with shared rules: I routinely work with 10+ different projects across unrelated directories. Most of them share the same baseline conventions (coding style, commit message format, security guidelines, etc.).

  2. Duplicate-and-sync hell: Every new project needs a manual copy of the same AGENTS.md. When our team updates a convention, I have to remember and sync every single project's file. This is tedious and error-prone — some repos inevitably get outdated rules.

  3. Skills are not a replacement: Skills are loaded on-demand, so they cannot guarantee baseline rules are always followed. I need certain rules (like "always use 4-space indentation" or "never commit secrets") to be injected at session start, not left to the AI's discretion.

Proposed Solution

Load a global AGENTS.md from ~/.kimi/AGENTS.md (or ~/.kimi/agents.md) before the project-level one. The project-level file can then override or extend the global rules.

Example precedence:

  1. ~/.kimi/AGENTS.md — global baseline (optional, opt-in)
  2. <project-root>/AGENTS.md — project-specific overrides

This is the same pattern used by .gitconfig (~/.gitconfig + repo-level overrides) and many other tools.

Why This Matters

In real-world enterprise/team environments, developers often work with many repos that should all follow the same standards. A global config acts as a "default floor" without forcing per-repo duplication.

Opt-in Design

This is purely optional. Users who don't need it simply don't create ~/.kimi/AGENTS.md. Zero impact on existing workflows. Those who need it get a much better multi-project experience.

Related

  • Discussion #955 (converted from original Issue #439)
  • PR #474 (previous attempt, closed)
  • PR #1590 (community follow-up, awaiting review)

Please reconsider this feature. The "more compelling reasons" asked for in #439 is right here: multi-project maintenance is a daily pain point that Skills simply cannot solve.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing Discussion #955 and the prior attempts in PR #474 and PR #1590, then trace how the CLI currently loads AGENTS.md from the working directory. Done means an optional ~/.kimi/AGENTS.md is loaded before the project-level file, with project rules able to override or extend the global conventions.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
cli
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.