tinygent

Reusable AI agent sessions from the command line.

tinygent is a tiny Node.js npm CLI for running Codex-backed AI agent workflows with reusable sessions, identity files, user-defined tools, and script-friendly command-line automation.

• Website: https://skbilisim.com/en/projects/tinygent
• npm: https://www.npmjs.com/package/@sksoftofficial/tinygent

Usage

Onboard

tinygent onboard

Optional agent id:

tinygent onboard --agent main

Optional message rotation limit:

tinygent onboard --agent main --message-rotation-limit 25

Optional session retention limit. This keeps the newest session log files and deletes older ones automatically after a message creates or rotates a session. Press Enter during onboarding to use the default of 10.

tinygent onboard --agent main --session-retention-limit 10

Login

Replace Codex credentials for an agent without changing identity, tools, session config, or session state:

tinygent login --agent main

Send a message

tinygent message "hi"

With explicit model:

tinygent message --agent main --model gpt-5.5 "hi"

Override reasoning level for this message. Defaults to low; supported levels are none, minimal, low, medium, high, and xhigh.

tinygent message --reasoning none "hi"

From file:

tinygent message --file ./prompt.txt

Force a fresh session:

tinygent message "start fresh" --new-session

Use a custom session id:

tinygent message --session-id editorial-thread-1 "continue this thread"

Identity

Print the current identity.md for an agent:

tinygent identity

For a specific agent:

tinygent identity --agent main

Overwrite identity.md with the contents of a file:

tinygent identity --agent main ./identity.md

Tools

Tools from tools.js are loaded automatically during tinygent message. If the model requests a tool call, tinygent executes it, appends the tool result to the session, and continues until the final answer.

Tinygent also includes two built-in media tools:

• image analyzes one or more image paths, URLs, or data URLs with a vision model.
• image_generate generates or edits images with OpenAI image models, defaulting to openai/gpt-image-2, and saves results under ~/.tinygent/<agent>/media/.

image_generate uses the agent's Codex credentials from tinygent onboard or tinygent login.

Print the current tools.js for an agent:

tinygent tools

For a specific agent:

tinygent tools --agent main

Merge tools from a file into the agent's existing user tools. Built-in tools remain available during tinygent message:

tinygent tools --agent main ./tools.js

Replace the complete tool set instead of merging, including built-ins:

tinygent tools --agent main --override ./tools.js

Clear session state

tinygent clear

For a specific agent:

tinygent clear --agent main

List agents

tinygent agents

Status and usage

Report Codex subscription usage:

tinygent status

For a specific agent:

tinygent status --agent main

Example:

Usage: 5h 47% left 1h 24m · Week 81% left 5d 2h

Refresh credentials

tinygent refresh

If the refresh token is no longer valid, run tinygent login --agent main to sign in again without rerunning onboarding.

Workspace layout

Per agent workspace:

~/.tinygent/<agent>/
  codex-credentials.json
  identity.md
  tools.js
  session-config.json
  current_session.txt
  custom-session-mappings.json
  sessions/