Firstly, thanks for a very useful tool.

I tried creating an agent within the AiChat framework for this. The purpose of it to enbling understanding of the context of a series of scripts that I call from Terminal (macOS). So it can suggest syntax the way you can do: aichat -e "how do I see the files in the folder".

I ran into a problem. I may have missed something in the docs, but I found the local agent setup a bit hard to infer.

The example says the agent-specific config lives at:

<aichat-config-dir>/agents/<agent-name>/config.yaml

I created that file, but aichat --list-agents did not show the agent and aichat -a gradechat returned:

Unknown agent 'gradechat'

After checking the v0.30 source code, I realized that local agent discovery also depends on:

<aichat-config-dir>/functions/agents.txt

and:

<aichat-config-dir>/functions/agents/<agent-name>/index.yaml

So it seems agents/<agent-name>/config.yaml is only the agent-specific configuration, while functions/agents/<agent-name>/index.yaml is the actual agent definition/discovery file.

Would it be possible to add a small “minimal local custom agent” example to the docs, e.g.:

<aichat-config-dir>/
  functions/
    agents.txt
    agents/
      my-agent/
        index.yaml
  agents/
    my-agent/
      config.yaml   # optional overrides

I’m happy to submit a docs PR if this structure is correct.