From b90e0b9db57a0b9a8e8792e6e1b0c212e6606cc6 Mon Sep 17 00:00:00 2001
From: Christina Tong <christina@letta.com>
Date: Fri, 13 Feb 2026 19:45:40 -0800
Subject: [PATCH] feat: add tags to headless (#957)

---
 src/agent/create.ts | 5 +++++
 src/headless.ts     | 3 +++
 src/index.ts        | 1 +
 3 files changed, 9 insertions(+)

diff --git a/src/agent/create.ts b/src/agent/create.ts
index 18f1f23..23c5cbc 100644
--- a/src/agent/create.ts
+++ b/src/agent/create.ts
@@ -73,6 +73,8 @@ export interface CreateAgentOptions {
   >;
   /** Override values for preset blocks (label → value) */
   blockValues?: Record<string, string>;
+  /** Tags to organize and categorize the agent */
+  tags?: string[];
 }
 
 export async function createAgent(
@@ -290,6 +292,9 @@ export async function createAgent(
   if (isSubagent) {
     tags.push("role:subagent");
   }
+  if (options.tags && Array.isArray(options.tags)) {
+    tags.push(...options.tags);
+  }
 
   const agentDescription =
     options.description ?? `Letta Code agent created in ${process.cwd()}`;
diff --git a/src/headless.ts b/src/headless.ts
index 6e4de54..a436a3e 100644
--- a/src/headless.ts
+++ b/src/headless.ts
@@ -124,6 +124,7 @@ export async function handleHeadlessCommand(
       "init-blocks": { type: "string" },
       "base-tools": { type: "string" },
       "from-af": { type: "string" },
+      tags: { type: "string" },
 
       memfs: { type: "boolean" },
       "no-memfs": { type: "boolean" },
@@ -268,6 +269,7 @@ export async function handleHeadlessCommand(
   const fromAfFile = values["from-af"] as string | undefined;
   const preLoadSkillsRaw = values["pre-load-skills"] as string | undefined;
   const maxTurnsRaw = values["max-turns"] as string | undefined;
+  const tags = values["tags"] as string[] | undefined;
 
   // Parse and validate max-turns if provided
   let maxTurns: number | undefined;
@@ -581,6 +583,7 @@ export async function handleHeadlessCommand(
       baseTools,
       memoryBlocks,
       blockValues,
+      tags,
     };
     const result = await createAgent(createOptions);
     agent = result.agent;
diff --git a/src/index.ts b/src/index.ts
index 5eb75a5..9c9ff74 100755
--- a/src/index.ts
+++ b/src/index.ts
@@ -439,6 +439,7 @@ async function main(): Promise<void> {
         "pre-load-skills": { type: "string" },
         "from-af": { type: "string" },
         import: { type: "string" },
+        tags: { type: "string" },
 
         memfs: { type: "boolean" },
         "no-memfs": { type: "boolean" },