[Feature]: Support reading in cursorrules.md files

[openhands-agent]

What problem or use case are you trying to solve? The user is requesting support for .cursorrules.md files to enhance functionality. Currently, these are not directly supported, as mentioned in the Slack thread.

Describe the UX of the solution the user wants The user appears to want direct integration and readable support for .cursorrules.md files, possibly to avoid manual addition to chats.

User's thoughts on the technical implementation? The mentioned alternative is leveraging mechanisms like https://docs.all-hands.dev/modules/usage/prompting/microagents-repo for similar functionality.

Describe the alternatives considered The user mentioned manually adding rules to chats, which is not ideal.

Additional context Relevant documentation link provided in the Slack thread: https://docs.all-hands.dev/modules/usage/prompting/microagents-repo

Issue Created By: Graham Neubig on Slack

Link to Slack Thread: https://openhands-ai.slack.com/archives/C06U8UTKSAD/p1742415685622419?thread_ts=1742415685.622419&cid=C06U8UTKSAD

If you find this feature request or enhancement useful, make sure to add a 👍 to the issue

[AutoLTX]

@neubig I'm interested about the issue and I like to contribute for it. Please assign it to me if no one is working on it. Just want to confirm one thing with you first, which type of support are we preparing to do?

• Support it like exising repo.md https://docs.all-hands.dev/modules/usage/prompting/microagents-repo
• Support it like cursor. https://docs.cursor.com/context/rules-for-ai

Both are acceptable to me. I'd like to confirm with you first before starting the design/implementation 😊

[neubig]

Hey @AutoLTX , thanks! I'm not 100% sure what you mean by this, could you clarify a little bit what you mean by these two options? What would they look like for the OpenHands user?

[BradKML]

Is this about self-modifying prompts that Cursor was actively removing through .mdc file formats?

[AutoLTX]

Hi, @neubig Let me try to clarify it clearly.

• For option1, if we support it like existing repo.md. Then we will use something like Symlink or concat the repo.md and .cursorrules together. And then the file will be handled following the mechanism of original repo.md. For users, they can use both repo.md and .cursorrules to adopt their rules. .cursorrules is just another repo.md.
• For option2, we support the latest cursor rule pattern. For users the rules should be hosted in .cursor/rules. The files should be something like xxx.mdc. And support specific features for rules like the the one in cursor.(Following https://docs.cursor.com/context/rules-for-ai) I've roughly go through the doc and find something like: different level rules(project/global) support, path specific configurations...

Cursor has already made the decision to deprecate the cursorrules finally. I agree to have backward compatibility as .cursorrules is still widely used by many customers. So I prefer to support for both .cursorrules + .cursor/rules, including new features of latest cursor rules. Like:

• Files are hosted under .cursor/rules, with mdc suffix.
• Specific level rules. Distinguish project and global level rules.
• Reference doc attach....

Do you think it's acceptable? I prefer to have a detailed investigation about it and draft a design doc, including the final scope and features I prepare to support. Break down the tasks and implement it one by one gradually. This can also make sure my full working process is trackable.😊 By the way, do we have some tools to track the work item? Or just track the status in this thread/slack is acceptable?

[BradKML]

Welp .cursorrules and their windsurf/roocode equivalents are pretty useful for self-updating agents, so there needs to be a way to keep that up as well... Or until there is a way to self-add "sub-rules" by the agent. Will get some example of how they probably should look like in a moment

[neubig]

Ok, I think option 1 sounds good! And status tracking on GitHub issues and slack is good.

[caique]

Hey folks!

My 2cents about this:

• the .cursor/rules is the latest version of rules while .cursorrules is somehow legacy. Maybe we should aim for scanning .cursor/rules (or both for the sake of backwards compatibility with old Cursor users)
• it is not clear from Cursor on how the trigger of the rules is done. But, feels a lot like OH "knowledge microagents" that are triggered by keywords and not the repo.md.

[neubig]

Hey @AutoLTX , just checking in on this, have you had a chance to take a look?

[AutoLTX]

Hey, @neubig for this one. It seems there are some different opinions in the discussion according to the option1 we chose. I decide to link the .cursorrules with repo.md first to have a initial version backwards compatiblity support for old cursor users.

I prepare to implement the full logic like new .cursor/rules. (For context, you can go back to check the options I provided 3 weeks ago.)

I will break these into different work and do option1 as temporarily solution first. Do you think it's accepable?

[neubig]

Yes, for sure. I think doing the simpler thing first and a more complex thing later is reasonable.

[neubig]

Hey @AutoLTX , just checking in if you'd had a chance to take a look at this? If so that'd be great, if not we could have someone else take a look too.

[AutoLTX]

Yes, I will create a PR for the old .cursorrules related basic support with option1 at the end of this weekend to make sure I have real progress for this.

[neubig]

Great, thank you!

[enyst]

A little heads up here: we now load any .md files in microagents/, and if they don't have triggers specified, then they are treated as repo.md. There is no limit for the number of repo.md-like files. Their contents are concatenated and sent in the prompt. I hope that makes this easier!

[github-actions[bot]]

This issue is stale because it has been open for 30 days with no activity. Remove stale label or comment or this will be closed in 7 days.

[neubig]

Hey @AutoLTX , thanks for sending a PR! Do you need any help with this?

[AutoLTX]

Hi, @neubig I will update soon. I found I miss an important part during test suddenly.

The legacy .cursorrules already support leveraging .mdc file. using @ .Originally I thought mdc related support would only affect .cursor/rules related support and prepare to support mdc related adoption later in a seperate PR before implementing cursor/rules.

I didn't notice it initially and misunderstand the complexity need for the work. Just link the .cursorrules with repo.md(like option1 we mentioned previously in the discussion thread) is not enough to cover .cursorrules' full ability. Need additional logic to cover this part. Sorry for the inconvenience. I will accelerate the speed. 😂 I know mdc related part is complex. I will write a draft design proposal this week to make sure we are aligned and I won't lose scope should be included this time.

I can also clean and merge the pr without .mdc support first if necessary. But if we do so, basic .cursorrules is supported. Complex .cursorrules referencing .mdc file will be ignored.(But it won't show error, just losing some of the context). And I will update other parts in another PR. Which one do you prefer?

[BradKML]

@AutoLTX thanks for the work, and I would like to note how .windsurfrules (Windsurf copying the old format) and .roo (RooCode copying the new format) are often used interchangeably, how would that be solved?

[AutoLTX]

I checked and found I misunderstood the legacy cursorrules has .mdc support in last response. This are still decoupled tasks. It's only supported in the later cursor/rules. So the previous PR make sense but it's too old and has conflict. I decide to create a new PR directly. I will create a PR tonight and trying to merge it to make sure the .cursorrules is supported and unblock some customers, and then continue the following things for advanced cursor/rules related work.

If I still didn't create the part1 tonight, feel free to reassign it to someone else.(I will try my best to make sure this won't happen. Thanks for the trust for waiting such a long time. Sorry for this and my misunderstanding.. I will learn from this experience and make sure it doesn't happen again next time. This time my idea is clear.)

[BradKML]

Welp looks like it got merged, that is good at least, and yet there are still .mdc extensions out there, they probably act more more like microagents? Not sure, but if there are places in OH to review some of the rule-bundles that would be great

[enyst]

The same places as the PR used, are the places in OH to load .md files from a repo.

We can definitely add more; we can, in time, convert the code to make it more clear what comes from where, and maybe adapt our microagents to offer the ability to load files by different criteria than those we currently have implemented.

[AutoLTX]

I prepare to finish the Part2 .cursor/rules and .mdc related support first.(I will give a final ETA for this next week after estimation and make sure I won't broke the ETA). And then I can draft a plan for your idea and we can have a further discussion? @enyst Do you think the sequence make sense? Or do I need a seperate issue to track the work?

[enyst]

No worries, I just answering to Brad. .cursor/rules and .mdc support sounds great! Thank you!

[BradKML]

@AutoLTX thanks for the great work, if I need to share some of the .mdc I find in the wild to integrate as microagents, I would definitely share it in a different issues, there are some "project management" stuff that would be somewhere between MCP and "rules"

[AutoLTX]

Task breakdown for .cursor/rules related implementation plan.

Core logic

• [ ] (Review advice from @enyst ) Always load .cursorrules, regarding of whether microagent directory exists. Same for cursor/rules.
• [ ] Implement loading mechanism for .cursor/rules directory and its files.
• [ ] Enforce rule scoping: rules in subdirectory '.cursor/rules' should only apply to that folder and its subdirectories.
• [ ] Parse MDC files with yaml formatter and markdown content.
• [ ] Support referencing additional context files using '@' syntax inside mdc content when the rule triggers.

Rule Types & Behavior

• [ ] [Needs UI] Support for both Project Rules and User Rules.
  → Consider reusing logic from microagents/ if applicable.
• [ ] [Needs UI - dropdown] Support for different rule types: Always, Auto Attached, Agent Requested, Manual.
• [ ] Version control awareness for rule files (e.g., Git-tracked changes).

(Open Question) UI for rules

• [ ] Provide UI surface for browsing and managing rules.
• [ ] Select rules type in UI.
• [ ] Project/User level rules.

Testing

• [ ] Test coverage for all features above.

Extensibility

• [ ] (Optional, Long term) Refactor rule system to support pluggable rule types from trending AI coding product easier.(Windsurf/Roocode...).

Hi, @enyst , @neubig , @BradKML I've tried to break down the tasks for full cursur/rules suppport. Could you please take a review at it? Additionaly is it ok if I create a new issue to track this and referencing current issue because it's more than .cursorrules now?

[enyst]

Hey @AutoLTX ! Thank you for this. A few notes

These are very okay, and don't need to be longterm; we can just add them to the current implementation whenever you like:

Always load .cursorrules, regarding of whether microagent directory exists. Same for cursor/rules. Implement loading mechanism for .cursor/rules directory and its files. Windsurf/Roocode...)

Windsurf has .windsurfrules, which behave the same as repo.md (and .cursorrules), so why not add the file alongside .cursorrules? Same for roocode, same for AGENT.md and AGENTS.md. Maybe we already support those files? Maybe we need unit tests to make sure.

Enforce rule scoping: rules in subdirectory '.cursor/rules' should only apply to that folder and its subdirectories.

I'd suggest a new issue for this, please feel free to correct the contents if I got this wrong:

• https://github.com/All-Hands-AI/OpenHands/issues/9878

I'd also suggest a new issue for this:

• https://github.com/All-Hands-AI/OpenHands/issues/9879

I'm not sure if we need to do anything special in the UI, because we hopefully don't need to create UI for Cursor or others? What we name here "rules" are microagents. We have some support for microagents in the UI, don't we?

Project/User level rules.

This sounds right to me, if it's for all microagents. I think we introduced recently user-level microagents, and I'm not sure they're in FE, maybe we could add them if not. I don't think this is about Cursor rules, though, but about all.

What am I missing?

[BradKML]

As a heads up @AutoLTX take a look at this as well https://github.com/intellectronica/ruler

[AutoLTX]

Hi, @enyst Thanks for the comment. There is a confusion part for the real purpose here.

• Originally I thought the target is supporting the cursor/rules and other rules in trending codeai product to ensure users can have a smooth migration if they want to try openhands.
• It seems your preference is checking what's useful in the cursor/rules and pick some of the features in the microagent mechanism?

What's the real target for it

[enyst]

Oh, good question! In my view, one leads to the other:

This is indeed a goal:

supporting the cursor/rules and other rules in trending codeai product to ensure users can have a smooth migration if they want to try openhands

Then, the question becomes: how do we support them?

“How” = in the microagents system in openhands.

Supporting something like .windsurfrules is straightforward I think: we read the file like a repo.md microagent.

Supporting some features we don’t yet have, like directory scope, implies, to me, that we’d need to support it first in the microagents system, then also include those name patterns from other AI products. (assuming we want that behavior)

Did that make sense?

[AutoLTX]

Make sense, thanks for the explanation.😉