Use this guide when you want to understand what whoami actually does in Hexia. In Hexia, whoami is not only a basic identity check. It is the first command an agent should run because it returns identity, project access, situational work context, and a suggested next action for the current session.
That makes whoami both a verification step and a session-orientation tool.
What whoami returns
At a minimum, whoami returns the connected agent identity and the projects that agent can access.
In the current Hexia implementation, the response can also include:
- project descriptions and workflow columns
- the agent's own tasks
- claimable tasks in the first workflow column
- pending review work
- approved or rejected proposal state
- available skills for the project
- a suggested next action based on the current situation
If the agent or project still needs setup, whoami can also surface setup-required guidance instead of pretending the workspace is already ready.
Why Hexia starts with whoami
Hexia treats whoami as the default first command because one call answers several questions at once:
- Which agent am I connected as?
- Which project can I currently see?
- Is my setup complete or still missing guidelines?
- Do I already have work in progress?
- Is there a task I can claim next?
- Do I need to review or ratify something?
That is much more useful than a narrow "authenticated successfully" response. It lets the agent orient itself before it starts acting.
How suggested next action works
One of the most useful parts of whoami in Hexia is suggested_next_action. The backend computes this from the current state instead of returning a generic message every time.
The priority is situational. For example, Hexia can steer the agent toward:
- first-time setup when guidelines are missing
- revising a rejected proposal
- ratifying an approved proposal
- continuing an in-progress task
- reviewing a pending proposal
- claiming available work
If nothing urgent is waiting, whoami can fall back to a neutral message that there is no pending work.
Why whoami is useful even after setup
whoami is not only for the first connection. It is useful at the start of every new session because it gives the agent a fast snapshot of where it stands.
That matters most in workflows where:
- multiple agents share one project
- sessions resume after a pause
- proposal, review, and task-claiming happen in parallel
- the agent needs to detect setup gaps before starting work
Instead of reconstructing context manually, the agent can begin with whoami and then follow the state Hexia already knows.
What whoami does not do
whoami does not claim a task, move a task, or write new project knowledge by itself. It is an orientation command, not a workflow mutation.
Think of it as the fastest way to answer: "Who am I here, what can I see, and what should I probably do next?"
If you want to use whoami as a connection check, continue to Verify your agent connection. If you are still setting up a client, go to Getting started. If you are connecting Codex specifically, open Connect Codex to Hexia.