Hi to everyone! I am happy for being part of this community, and after lurking for some time, i felt like i may have done something worth posting here too, i hope at least :) TL;DR I was building an API for an AI agent (specifically for Claude Code) and realized that traditional REST responses only return results, not guidance. This forces LLM agents to guess formats, parameters, and next steps, leading to trial-and-error and fragile client-side prompting. TEKIR solves this by extending API responses with structured guidance like next_actions , agent_guidance , and reason , so the API can explicitly tell the agent what to do next - for both errors and successful responses. It is compatible with RFC 9457, language/framework independent, and works without breaking existing APIs. Conceptually similar to HATEOAS, but designed specifically for LLM agents and machine-driven workflows. The long story I was building an API to connect a messaging system to an AI agent (in my case mostly Claude Code), for that I provided full API specs, added a discovery endpoint, and kept the documentation up to date. Despite all this preparation and syncing stuff, the agent kept trying random formats, guessing parameters, and doing unnecessary trial and error. I was able to fine tune the agent client-side and then it worked until the context cleared, but I didn’t want to hard code into context/agents.md how to access an API that will keep changing. I hate all this non-deterministic programming stuff but it’s still too good to not do it :) Anyway, the problem was simple: API responses only returned results, because they adhered to the usual, existing protocols for REST. There was no structure telling the agent what it should do next. Because of that, I constantly had to correct the agent behavior on the client side. Every time the API specs changed or the agent’s context was cleared, the whole process started again.
That’s what lead me to TEKIR . It extends API responses with fields like next_actions , agent_guidance , and reason , allowing the API to explicitly tell the AI what to do next and this applies not only to errors, but also to successful responses (important distinction to the existing RFC for “Problem Detail” at https://www.rfc-editor.org/rfc/rfc9457.html but more on that later). For example, when an order is confirmed the API can guide the agent with instructions like: show the user a summary, tracking is not available yet, cancellation is irreversible so ask for confirmation. TEKIR works without breaking existing APIs. It is compatible with RFC 9457 and is language and framework independent. There is an npm package and Express/Fastify middleware available, but you can also simply drop the markdown spec into your project and tell tools like Claude or Cursor to make the API TEKIR-compatible. RFC 9457 “needed” this extension because it’s too problem oriented, it’s explicitly for problems (errors), but this goes beyond that. This is a guideline on future interactions, similar to HATEOAS - but with better readability and specifically tailored to automated agents like Claude.
Why the name “Tekir”? “Tekir” is the Turkish word for “tabby” as in “tabby cat”. Tabby cats are one of nature’s most resilient designs, mixed genes over thousands of years, street-forged instincts, they evolved beyond survival, they adapt and thrive in any environment. That is the notion I want to bring forth with this dynamic API design too. There’s also a more personal side of this decision though. In January this year my beloved cat Çılgın (which means “crazy” in Turkish) was hit by a car. I couldn’t get it out of my head, so I named this project after him so that in some way his name can live on. He was a tekir. Extremely independent, very intelligent, and honestly more “human” than most AI systems could ever hope to be, maybe even most humans. The idea behind the project reflects that spirit: systems that can figure out what to do next without constant supervision. I also realized the name could work technically as well: TEKIR - Transparent Endpoint Knowledge for Intelligent Reasoning
Feedback is very welcome. <<<<< Project page (EN / DE / TR) https://tangelo-ltd.github.io/tekir/ GitHub https://github.com/tangelo-ltd/tekir/ submitted by /u/Ok-Preparation-2643
Originally posted by u/Ok-Preparation-2643 on r/ClaudeCode